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PREFACE 



The iRMX 86 Operating System is a software package that provides a 
realtime, multitasking environment for Intel iAPX 86-based 
microcomputers, including the iSBC 86/12A single board computer. This 
manual contains the instructions that you need to configure an iRMX 86 
application system using Release 3.0 of the iRMX 86 Operating System. By 
following the instructions in this manual, you can use an INTELLEC Series 
II or Series III Microcomputer Development System to build an iRMX 86 
system. 



READER LEVEL 

This manual assumes that you are a system programmer, experienced in 
dealing with operating systems. In particular, it assumes you are 
familiar with the following: 

• The iRMX 86 Operating System and the iRMX 86 reference manuals 

• The 8086/8087/8088 Macro Assembly Language and/or PL/M-86 

• The INTELLEC Series II or Series III Microcomputer Development 
System 

• LINK86 and L0C86 

• The notions of segments, groups, and classes as they apply to 
assembly language, PL/M-86, LINK86, and LOC86 



NOTATIONAL CONVENTIONS 

The following conventions are used to show syntax in this manual: 

UPPERCASE Information appearing in uppercase must be entered or 
coded exactly as shown. This information, however, can 
actually be entered in uppercase or lowercase. 

lowercase Fields appearing in lowercase indicate variable 

information. The user must enter the appropriate value or 
symbol for variable fields. 
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CHAPTER 1. INTRODUCTION 



The Intel iRMX 86 Operating System is a software package designed for use 
with the Intel iAPX 86-based microcomputers. It is a powerful and 
flexible system around which you can build your application system. 

The iRMX 86 Operating System consists of a number of subsystems, some of 
which must be included in your application system, and some of which are 
optional. The subsystems of the iRMX 86 Operating System are: 



Nucleus 



This is the core of the iRMX 86 Operating 
System and is required by every application 
system. It provides services for the remainder 
of the software running in the system. 



Terminal Handler 



This is an optional subsystem that provides a 
real-time interface between your terminal and 
other software running under the supervision of 
the Nucleus. 



Debugger 



I/O System 



This is an optional subsystem that provides a 
facility for debugging and monitoring software 
running under the supervision of the Nucleus. 

This is an optional subsystem that provides 
asynchronous file access capabilities for 
software running under the supervision of the 
Nucleus . 



Extended I/O 
System 



This is an optional subsystem that provides high 
level, synchronous file access capabilities for 
software running under the supervision of the 
Nucleus. 



• Application 
Loader 



This is an optional subsystem that provides the 
capability to load object files into memory 
from disk under the control of the Operating 
System. 



Bootstrap Loader This is an optional subsystem that provides the 
capability to load the other subsystems and/or 
application jobs into memory from disk and 
begin system execution. 



Human Interface 



This is an optional subsystem that provides an 
interactive interface between a user and 
software running under the supervision of the 
Nucleus. 
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Software that you create runs in an iRMX 86 application system using the 
facilities of the Nucleus and the other subsystems. 

Configuration consists of selecting the subsystems that are appropriate 
for your system, tailoring them to meet your individual needs, and 
combining them with your own application software to form a functional 
application system. Figure 1-1 illustrates this. 



PARTS OF iRMX 86 
OPERATING SYSTEM 



BOOTSTRAP 
LOADER 



HUMAN INTERFACE 



EXTENDED 
I/O SYSTEM 



APPLICATION 
LOADER 




APPLICATION 
SOFTWARE 



SELECT PARTS OF iRMX 86 
OPERATING SYSTEM 
REQUIRED BY 
APPLICATION SOFTWARE. 




COMBINE APPLICATION 
SOFTWARE WITH iRMX 86 
OPERATING SYSTEM TO FORM 
APPLICATION SYSTEM. 



APPLICATION SYSTEM 









<& 


APPLICATION 
SOFTWARE 




iRMX 86 

OPERATING 

SYSTEM 









Figure 1-1. iRMX 86 w Application System 
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CONFIGURATION ENVIRONMENT 

The INTELLEC Microcomputer Development System provides the environment in 
which you create your application system. With the development system 
you can code and translate your user software, and link and locate the 
various components of the application system. Upon completion, you can 
load your iRMX 86 application system from the INTELLEC development system 
into an iAPX 86-based microcomputer using the ICE-86 in-circuit emulator, 
or the iSBC 957A package. 

The development system can also be used to run the Files Utility 
(described in the iRMX 86 INSTALLATION GUIDE ). The Files Utility can 
format iRMX 86 disks and copy your system onto disk. Then you can use 
the Bootstrap Loader to load your system. 



TASKS, JOBS, AND THE INITIAL SYSTEM 

Tasks are the active parts of an iRMX 86 application system. The 
subsystems contain tasks that perform some of the functions of the 
Operating System. Your application software also consists of one or more 
tasks. Each task is part of a job. A job is the environment in which 
tasks run; thus a job consists of tasks and the resources that they use. 
The iRMX 86 NUCLEUS REFERENCE MANUAL describes this in detail. 

The jobs in a system form a hierarchy. A task in one job can create 
other jobs. Tasks in the new jobs can create still other jobs, and so 
forth. The jobs which contain tasks that create other jobs are called 
parent jobs , and the jobs they create are their offspring . 

Task and job creation is a dynamic process. However, when you configure 
a system, you specify an initial system which is created automatically 
when the system starts executing. The job tree for an initial system 
consists of an ultimate parent job called the root job and a number of 
its offspring called first-level jobs . Intel supplies the root job. 
Some of the first-level jobs are jobs for the subsystems that your 
application system requires (the Debugger, the Terminal Handler, the I/O 
System, the Extended I/O System, the Application Loader, and/or the Human 
Interface). Intel also supplies these jobs as part of the subsystems. 
The remainder of the first-level jobs are jobs that you provide. Figure 
1-2 illustrates an initial job tree. 
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Figure 1-2. Initial Job Tree 



First-level jobs can spawn a number of offspring jobs, beginning the 
dynamic tree structure of the system. The iRMX 86 NUCLEUS REFERENCE 
MANUAL describes how to create new tasks and jobs. However, in order to 
create all of its offspring jobs, a first-level job must be able to 
determine where in memory the code for all of its offspring tasks 
resides. You provide this ability in one of two ways: 

• The easiest and most common way is by linking a first-level job 
and all of its offspring jobs together in one link module. This 
allows tasks in the first-level job to use symbolic names to 
specify the start addresses and data segment bases in calls to 
CREATE $ JOB. 

• If the code is too large to link together in one module, you can 
link and locate the tasks separately. However, this prevents 
some tasks from referring to other tasks with symbolic names. In 
this case, when a task in the first-level job creates offspring 
jobs or tasks, it must specify absolute values for the start 
address and data segment base parameters of CREATE$JOB or 

CRE ATE $ TASK. 

You must use one of these methods for each first-level job that you 
create. Chapter 4 contains a further description. When you configure a 
system, you must supply information to the root job about each 
first-level job. 
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TYPES OF SYSTEM CONFIGURATION 

When you define an iRMX 86 configuration, you may have one of several 
goals in mind. You may be putting together your first iRMX 86 system and 
thus want to test and debug the entire system. You may have gotten 
portions of the system working to your satisfaction, but now want to 
correct a few isolated bugs or add a new task or tasks. Or, you may have 
completely tested and debugged your system and now want to create the 
final ROM-based version. 

When building your first system, you should locate your entire system in 
RAM only. This saves you the trouble of burning code into PROM, only to 
have to reburn it later. 

When creating your final system, you must perform additional procedures 
because you are locating the system in two different areas of memory, ROM 
and RAM. In a ROM/RAM system, you must separate all of the ROM-resident 
parts of the system and locate them in ROM. 

When building an intermediate system, you have debugged and tested 
portions of your system, but are still developing or debugging others. 
In this case you have two options. Each time you make a correction you 
can use the same initial RAM-only configuration, and reload the entire 
system into RAM for testing. Or, you can follow the procedures for 
locating a ROM/RAM system for the stable portions of your system only, 
such as the Nucleus. If you burn the stable portions into PROM, you save 
the time of loading each time you generate a new system. 



USING THIS MANUAL 

Chapter 2 of this manual lists the procedure involved in building an iRMX 
86-based system in step-by-step instructions. You can read Chapter 2 
first as an overview and then use it later as an easy reference. 

Chapter 3 and Chapters 6 through 13 discuss creating your application 
jobs and selecting features of the subsystems that you want to include in 
your application system. You should read Chapters 3 and 6 and some or 
all of Chapters 7 through 13, depending on which subsystems you are 
including in your application system. 

Chapter 4 describes locating a test system in RAM. Use it when you are 
building your first system. It also contains step-by-step instructions, 
but in much more detail than in Chapter 2. 

Chapter 5 describes the modification you must make to your RAM configur- 
ation in order to make it a ROM/RAM configuration. Use it in conjunction 
with Chapter 4 to create either an intermediate or final system. 

Appendix A contains a sample configuration session for a RAM-based system. 

Appendix B describes the process of burning the .Nucleus code into PROM. 

Appendix C lists the system call requirements of each of the optional 
subsystems. 
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CHAPTER 2. PROCEDURAL OVERVIEW 



The process of defining and building an iRMX 86 application system 
involves a number of steps. The following overview illustrates the main 
points and refers you to appropriate sections of this manual for detailed 
descriptions. 

1. Build and generate a configuration file for each subsystem that 
you are going to include in your system. Refer to Chapter 6 for 
a discussion of the Nucleus, Chapter 7 for the Terminal Handler, 
Chapter 8 for the Debugger, Chapter 9 for the Basic I/O System, 
Chapter 10 for the Application Loader, Chapter 11 for the 
Bootstrap Loader, Chapter 12 for the Extended I/O System, and 
Chapter 13 for the Human Interface. 

2. Write code for and compile all application jobs that you want to 
be a part of the application system. Refer to Chapter 3 for 
further information. 

3. Prepare the memory map for your system. Refer to the "General 
System Layout" section of Chapter 4 for further information. 

4. Iteratively link and locate each subsystem and first-level 
application job in your application system. Record the pertinent 
information on the memory map. Refer to the "Iterative Link and 
Locate Process" section of Chapter 4 for further information. 

5. Build a configuration file containing a %J0B macro for each 
subsystem and first-level application job, one or more %SAB 
macros, and one %SYSTEM macro. Refer to the "Build The 
Configuration File" section of Chapter 4 for further information. 

6. Assemble the configuration file and link and locate the root 
job. Refer to the "Generate The Root Job" section of Chapter 4 
for further information. 

7. Using the ICE-86 in-circuit emulator or the iSBC 957A package, 
load the system into RAM. Refer to the "Load and Test The 
System" section of Chapter 4 for further information. 

8. Test and debug the system in RAM. Refer to the "Load And Test 
The System" section of Chapter 4 for further information. 

9. Lay out a ROM/RAM system, but load it into RAM for testing. 
Refer to Chapter 5 for further information. 

10. Load the final system into ROM/RAM. Refer to Chapter 5 for 
further information. 
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CHAPTER 3. PREPARING JOBS FOR SYSTEM CONFIGURATION 



Building a system involves linking and locating each job in the iRMX 86 
application system and providing the root job with information concerning 
the first-level jobs. Before you begin this process, you must make sure 
that the pieces of the system, the Intel-supplied jobs and your user 
jobs, are ready to be combined. This involves the following of two 
operations. 

• Preparing application jobs 

• Preparing the subsystems 

When you begin the configuration process, you do not need to have all the 
jobs in your system written, because configuration can be an iterative 
process. That is, you can build your initial system with only one 
application job, and test it, before adding more jobs into the system. 
In this way you can build on a stable system. Or, if all your 
application jobs are available, you can build your initial system with 
all of your application jobs present, and test and debug the entire 
system at once. Regardless of how you build your application system, the 
information provided in this chapter allows you to integrate jobs easily 
into the iRMX 86 environment. 



PREPARING APPLICATION JOBS 

You can write the code for your application tasks in either PL/M-86 or 
assembly language. This manual assumes that you are using PL/M-86. In 
order to use assembly language, you must use version 3.0 of the 
8086/8087/8088 Macro Assembly Language andadhere to the PL/M-86 calling 
conventions. These are described in the appropriate 8086/8087/8088 MACRO 
ASSEMBLER OPERATING INSTRUCTIONS manual. The iRMX 86 PROGRAMMING 
TECHNIQUES manual also contains information to help you write assembly 
language tasks. 

If you have any problems using the PL/M-86 language or compiling PL/M-86 
code, refer to the appropriate PL/M-86 manual, either the PL/M-86 
PROGRAMMING MANUAL FOR 8080/8085-BASED DEVELOPMENT SYSTEMS, the PL/M-86 
COMPILER OPERATING INSTRUCTIONS FOR 8085-BASED DEVELOPMENT SYSTEMS, or 
the PL/M-86 USER'S GUIDE FOR 8086-BASED DEVELOPMENT SYSTEMS. However, in 
order to make use of the features of the iRMX 86 Operating System, you 
must follow instructions additional to those provided in the PL/M-86 
manuals when writing your code. The following sections provide this 
information. 
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LANGUAGE REQUIREMENTS 

Note the following language requirements when writing your task code: 

• Designate all of your tasks as procedures. Do not use main 
modules in your application system. 

• If you are compiling your PL/M-86 code using any model other than 
large, specify the ROM compiler control. This causes the 
compiler to place the CONST segment in the CODE class, where it 
can be more easily loaded into ROM. You do not need to specify 
the ROM control for those programs compiled using the large 
model, because the compiler automatically does this for the large 
model . 

• Be careful of using the DATA and INITIAL statements. The DATA 
statement is valid only if you are using the PL/M-86 large model 
of computation or if you specify the ROM compiler control. The 
INITIAL statement cannot be used in a procedure if you are going 
to place that procedure in ROM. It can be used, however, if you 
are going to use the Bootstrap Loader or the Application Loader 
to load the procedure. 



INCLUDE FILES 

There are a number of files contained on the iRMX 86 release diskettes 
that can be included with your PL/M-86 procedures at compilation time. 
You must include some or all of these files, depending on the subsystems 
your programs make use of. Table 3-1 lists these files according to type 
and subsystem. You must include the files in the compilation of your 
procedures if those procedures use the system calls of the associated 
subsystems. For example, if your procedures make Nucleus and I/O System 
system calls, then you must include the four files associated with those 
subsystems in the compilation of your procedures. 

The INCLUDE files with the extension EXT contain the external PL/M-86 
declarations that procedures need in order to use the system calls of the 
associated subsystems. You can copy these files, edit them, and 
eliminate the external declarations for system calls that you do not use 
in your procedures. This can prevent dynamic storage overflow in the 
compiler. Refer to the iRMX 86 PROGRAMMING TECHNIQUES MANUAL f or further 
information. 

The INCLUDE files with the extension LIT contain the PL/M-86 declarations 
and assignments for the subsystem condition codes. 

To include the necessary files in the compilation of your procedures, use 
the PL/M-86 $INCLUDE control. Both the PL/M-86 COMPILER OPERATING 
INSTRUCTIONS FOR 8080/8085-BASED DEVELOPMENT SYSTEMS and the PL/M-86 
USER'S GUIDE FOR 8086-BASED DEVELOPMENT SYSTEMS describe this control. 
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Table 3-1. INCLUDE Files 



SUBSYSTEM 


EXTERNAL DECLARATIONS 


CONDITION CODE 




FILE 


FILE 


Nucleus 


NUCLUS.EXT 


NEXCEP.LIT 


I/O System 


IOS . EXT 


IEXCEP.LIT 


Application Loader 


LOADER. EXT 


LEXCEP.LIT 


Extended I/O System 


EIOS.EXT 


EEXCEP.LIT 


Human Interface 


HI. EXT 





SIZE CONTROL CONSIDERATIONS 

Part of the configuration process requires selectively locating various 
modules of the system (as described in Chapter 4). When you use class 
names on segment declarations you simplify this procedure. The PL/M-86 
compiler provides standard class designators for various segments of a 
program module. However, when writing your application code, be aware 
that the assignment of segments, classes, and groups in the PL/M-86 
output module varies according to the size control specified with the 
PL/M-86 compiler call. (Refer to the PL/M-86 COMPILER OPERATING 
INSTRUCTIONS FOR 8080/8085-BASED DEVELOPMENT SYSTEMS or the PL/M-86 
USER'S GUIDE FOR 8086-BASED DEVELOPMENT SYSTEMS for details.) 

The size control of the PL/M-86 compiler call also determines how certain 
registers are initialized. The next chapter discusses this in detail. 
It is recommended that you use the same PL/M-86 size control for all of 
your PL/M-86 jobs, and that any assembly language modules be compatible 
with this control. 



INITIALIZATION 

When you configure an application system, you specify an initial system 
consisting of a root job and several first-level jobs. When the system 
starts executing, the Nucleus creates the root job. A task in the root 
job, the root task, then creates each of the first-level jobs. Tasks in 
the first-level jobs create the remainder of the application system. 
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When created, each first-level job contains only a single task. That 
single task creates or starts the creation of all other objects required 
by the first-level job. Thus it is referred to as the initialization 
task for its job, even though it may perform other functions as well. It 
is important for you to synchronize the operation of each initialization 
task with that of the root task to ensure proper functioning of your 
application system. 

The root task is structured so that it creates the first-level jobs one 
at a time. It contains a programming loop that in general performs the 
following: 

Repeat for each first-level job 

1. Create first-level job 

2. Suspend root task (until resumed by a first-level job) 
Until finished 

End 

Each time the root task creates a first-level job, the root task suspends 
itself to allow the initialization task in the new job to perform 
synchronous initialization. Synchronous initialization consists of 
functions that must be performed immediately, before some other 
first-level job is created. Typically, this requires creating objects or 
making resources available that tasks in first-level jobs not yet created 
expect to be available when they themselves are created. (For example, 
the initialization task in the I/O System job must create the entire I/O 
System before it can allow the root task to create other first-level jobs 
that might make use of I/O System functions.) 

When the initialization task finishes its synchronous initialization, it 
must inform the root task that it is finished, so that the root task can 
resume execution and create another first-level job. The initialization 
task must always inform the root task that it has completed its 
synchronous initialization process by making the following procedure call: 

CALL RQ$END$INIT$TASK; 

This procedure call is not described in any other manual. It requires no 
parameters. When you call this procedure, the root task resumes 
execution, allowing it to create the next first-level job. You must 
include a call to RQ$END$INIT$TASK in the initialization task of each of 
your first-level jobs, even if the jobs require no synchronous 
initialization. If one of the first-level tasks does not include this 
call, the root job remains suspended and cannot create any of the 
remaining first-level jobs. File NUCLUS.EXT contains the external 
declaration for this RQ$END$INIT$TASK and the Nucleus interface library 
(described in Chapter 4) contains its code. 
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The amount of synchronous initialization that an initialization task must 
do depends on your job structure. You may require some of your 
initialization tasks to create all of the offspring jobs and a number of 
other objects before calling RQ$END$INIT$TASK. Some others may only have 
to perform one or two functions, call RQ$END$INIT$TASK, and then resume 
the process of initialization asynchronously. Still other initialization 
tasks may not have any synchronous initialization requirements and so can 
call RQ$END$INIT$TASK before performing any initialization. You must 
determine how the pieces of your system interact, and how they must be 
synchronized. 

Another important factor in initialization is the order in which the root 
job creates the first-level jobs. The amount of processing your 
initialization tasks must do before calling RQ$END$INIT$TASK may depend 
on which jobs the root task has already created and which jobs it has yet 
to create. The order in which the root task creates first-level jobs 
depends on the order that you specify these jobs in a configuration file, 
not on the priority of the tasks in those jobs. (Refer to the 
description of the %JOB macro in Chapter 4.) Always specify the %JOB 
calls for the subsystems first, so that they are created and initialized 
first and are available to all other jobs. The order in which you 
specify your other first-level jobs depends on your application system. 

You should always use RQ$END$INIT$TASK as described in this section in 
order to perform your synchronous initialization. Do not attempt to 
accomplish the same function by temporarily raising and lowering task 
priorities. The iRMX 86 Operating System does not guarantee that your 
tasks will execute in the correct order if you use priorities to 
determine initialization order. 



PREPARING THE SUBSYSTEMS 

The subsystems have been created in a manner that allows you to choose 
system calls and features that you want to have available in your 
system. To prepare them, you must create tables that select or omit 
features. You must create these tables in a format understandable to the 
8086/8087/8088 Macro Assembler, assemble them, and link them to the 
subsystems. The details of preparing individual subsystems are contained 
in Chapters 6 through 11. 
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After you have prepared your application jobs and the subsystems, you 
should locate your first system entirely in RAM to facilitate testing and 
debugging of your programs. It is much easier to test and debug your 
programs in RAM than it is to continually reburn your PROMs when you 
detect errors. After debugging in RAM, you can locate the final system 
in ROM/RAM or copy it to a secondary storage device and load it with the 
Bootstrap Loader. 

Putting together a RAM-based system consists of the following steps: 

1. Laying out the system 

2. Linking and locating the Nucleus and application jobs 

3. Building the configuration file 

4. Generating the root job 

5. Loading and testing the system 

If you wish, the linking and locating can be separate steps. That is, 
you can use LINK86 to link any or all of your subsystems and jobs before 
ever starting the locate process. However, because the release diskettes 
for each subsystem contain SUBMIT files that link and locate the 
subsystems in one step, this manual considers the link and locate 
processes together. The following sections discuss the steps in more 
detail. 



GENERAL SYSTEM LAYOUT 

Linking and locating a system is an iterative process. That is, you must 
link and locate one first-level job and the offspring jobs, examine the 
locate maps to determine the ending address, and use that information to 
link and locate the next first-level job and offspring jobs. Therefore, 
before you use LINK86 to link the pieces of your system together and 
LOC86 to assign absolute memory addresses, you must decide where in 
memory to start locating the pieces, and in which order to locate them. 
The following sections discuss the various factors that you must consider 
when laying out your system. 
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NOTE 

This manual assumes that you link each 
first-level job together with its 
offspring jobs to produce a single link 
module, referred to as the first-level 
job, which you then locate at an 
absolute address. If you do not link 
your jobs together, you should follow 
the same locate procedure outlined in 
this chapter, but locate every job, not 
just the first-level jobs. 



SYSTEM TYPE 

At first, when creating an initial test system, you should locate all of 
your modules in RAM. This allows you to lay out the system on a 
job-by- job basis. You can locate all segments associated with one job 
(code segments, data segments, etc. ) sequentially in RAM and locate all 
segments of the next job following the first. 

Later, if you locate a final ROM/RAM system, you must locate the system 
by class, not by job. You must locate the code classes from all of the 
jobs at ROM addresses, and the data, stack, and memory classes at RAM 
addresses. Chapter 5 describes locating a ROM/RAM system. For now, 
however, lay out your system on a job-by- job basis, totally in RAM. 



HIGH AND LOW LOCATION OF MODULES 

You can locate the system either high or low in memory. When locating 
high in memory, assign the first module to the numerically largest 
absolute memory locations and the succeeding modules to numerically 
smaller locations. When locating low in memory, assign the first module 
to the numerically smallest memory locations and the succeeding modules 
to numerically larger locations. This manual assumes low location of 
modules because it is the easiest method to use with the iterative link 
and locate process that this chapter describes. 



MODULE ORDER 

The order in which you lay out your modules in memory should depend on 
the relative stability of the modules. You must later create a system 
configuration file that contains addresses of various parts of your 
system. If you can keep the stable portions of your system located at 
constant addresses, you can minimize modifications to the system 
configuration file. 
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Although you can change the sizes of the Nucleus and the subsystems by 
reconfiguring them, it is likely that their sizes will remain constant 
during your development cycle. Therefore, locate these modules first. 
Locate any of your application jobs that are subject to change later in 
memory, so that their size fluctuations do not necessitate changing the 
addresses of the other modules. In general, lay out your system as shown 
in Figure 4-1. 



APPLICATION FIRST-LEVEL 
JOBS 



ROOT JOB 



OPTIONAL SUBSYSTEM 
FIRST-LEVEL JOBS 



NUCLEUS 



LOW RAM ADDRESSES 



Figure 4-1. General System Layout 



Notice that Figure 4-1 illustrates locating the root job. Later sections 
of this chapter discuss the root job. For now, just note its position in 
the system layout. 

As you continue to test and debug your system, you may wish to create a 
fairly stable system with just a few user jobs and use that system as a 
base on which to build, testing and debugging each new job you add before 
adding others. If so, use the layout shown in Figure 4-1 for your first 
system and locate any new jobs you add at the end, where there is space 
available for them to grow during the debugging period. 



PREPARING A MEMORY MAP 

After you have decided in general how to lay out your system, prepare a 
memory map to indicate this. Figure 4-2 is a worksheet that you can use 
for this. To prepare a memory map, do the following: 
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1. In the right column of the worksheet, record the highest RAM 
address in your system. Notice that addresses corresponding to 
the beginning and end of the interrupt vector and reset vector 
have already been recorded. If you intend to use the iSBC 957A 
package to load your system into the iSBC 86/12A, reserve the 
locations 40:0 through 6F:F for the iSBC 957A monitor. 

2. In the center column of the worksheet, list the modules in the 
order you wish to locate them, one to a line, with the first 
module (the Nucleus) closest to the bottom of the worksheet. 

3. In the right column, on the same line as the first module, record 
the lowest available RAM address. Use this value when locating 
the first module. 

After you have made this map, use it during the link and locate procedure 
to condense the important information from the locate maps. You can use 
it to record the starting and ending locations of the modules, as well as 
other important information, such as entry points and data segment bases. 
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iRMX 86 w SYSTEM MEMORY MAP WORKSHEET 



Configuration file name: 

Start address/ 
Data segment base 



Module 



Length 



Absolute 
Address 



(reserved) 



reset vector 



Interrupt vector 



< 



FFFF : F 



/ FFFF:0 



K 
_/ 



K 
K 



< 
K 
K 



K — 

S' 40:0 

_ < / 0:0 



Figure 4-2. System Memory Map 
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Example: 

This example shows how to prepare a memory map worksheet for a sample 
system. The sample system has the following characteristics: 

• 128K of contiguous RAM exists in the system. Thus the highest 
RAM address is 1FFF:F. 

• The system consists of four modules: the Nucleus, the Debugger, a 
first-level application job, and the root job. 

• The iSBC 957A package is going to be used to load the system into 
memory. Therefore, the lowest available address is 70:0. This 
system starts with 1C0:0 as the first address to allow for future 
inclusion of the Bootstrap Loader (although if you are going to 
use the Bootstrap Loader with a device similar to to an iSBC 215 
device, you should allow more room and start at 200:0). 

Figure 4-3 shows a prepared memory map for this system. When the modules 
are located, actual addresses can be recorded on this worksheet. 
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iRMX 86 w SYSTEM MEMORY MAP WORKSHEET 



Configuration file name: 

Start address/ 
Data segment base 



Module 



Length 



Absolute 
Address 



(reserved) 



reset vector 



Highest RAM address 



Application Job 



Root Job 



Debugger 



Nucleus 



Interrupt vector 



FFFF : F 

FFFF:0 
1FFF:F 



< 



< 
< 
< 



1C0:0 

40:0 
0:0 



Figure 4-3. Example Memory Map Worksheet 
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LINK AND LOCATE THE SUBSYSTEMS AND APPLICATION JOBS 

After you have laid out your system, you can begin the iterative process 
of linking and locating your system. The following sections discuss this 
process. The first two sections discuss the procedures used to link and 
locate individual subsystems and application jobs. The third section 
describes how you must combine these individual link and locate processes 
and put together the entire application system. 



LINKING AND LOCATING THE SUBSYSTEMS 

The release diskette for each subsystem contains a SUBMIT file that 
assembles the subsystem's configuration files, links the necessary 
modules together, and locates the subsystem at an absolute address. 
These SUBMIT files can be run on a Series II Microcomputer Development 
System. Chapters 6 through 11 identify the SUBMIT files for each 
subsystem and describe their parameters. This section provides an 
overview of the general process, describes some restrictions that you 
must adhere to in order to use the SUBMIT files as released, and 
describes the modifications you must make to the SUBMIT files if you run 
them on a Series III Microcomputer Development System. 



Overview 

Figure 4-4 illustrates the procedure that most of the subsystem SUBMIT 
files follow in order to produce linked and located subsystems. This 
procedure includes assembling (or compiling) the subsystem configuration 
file or files, linking the object files together with the subsystem 
library or libraries (which contain the actual code for the subsystem) 
and any necessary interface libraries, and locating the resulting link 
module at absolute addresses. You can examine the individual SUBMIT 
files to determine the commands used, if you wish. However, after you 
have modified your subsystem configuration files to reflect your desired 
system, prepared the diskettes correctly, and placed them in the proper 
Series II development system disk drives, you need only use the ISIS-II 
SUBMIT command to run the SUBMIT files. (If you use a Series III 
development system, you will have to make additional modifications to the 
SUBMIT files in order to take advantage of the Series III capabilities.) 
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SUBSYSTEM 

CONFIGURATION 

FILE(S) 



ASM86 

OR 
PLM86 



CONFIGURATION 
OBJECT FILE(S) 



SUBSYSTEM 

UBRARY OR 

LIBRARIES 



INTERFACE LIBRARIES 
(EXCEPT FOR NUCLEUS) 



LINK 86 



LINKED SUBSYSTEM 



1 

LOC86 



LOCATED SUBSYSTEM 



Figure 4-4. Subsystem SUBMIT File Procedure 



Preparing Diskettes 

When you configure individual subsystems, you should never make 
modifications to the actual release diskettes. If you want to change any 
of the files on the release diskettes, such as the subsystem 
configuration files (named file.A86 or file.P86) or the SUBMIT files 
(named file.CSD), copy these files to another diskette first. 
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Placing Diskettes in the Proper Drives 

In order to use the subsystem SUBMIT files as they are released, you must 
place your diskettes in the proper drives of the INTELLEC development 
system. All subsystem SUBMIT files assume that you have a four drive 
development system and that you have placed diskettes in the drives as 
follows: 

FO A system disk containing LINK86, LOC86, ASM86 (version 3.0), 
and/or PLM86, as well as COPY, DELETE, and SUBMIT. 

Fl A diskette on which you should place any modified versions of 
configuration files and copies of all SUBMIT files. The 
SUBMIT files also write the located code for the subsystems 
to this diskette. If you need to make changes to any file on 
a release diskette, you should first copy it from the release 
diskette to this diskette and then make the changes. If you 
copy a configuration file to this diskette and make changes 
to it, you will also have to make changes to its associated 
SUBMIT file to correct the drive number for the configuration 
file. You should copy all SUBMIT files to this diskette 
before entering the SUBMIT command, so that you can leave 
your release diskettes in a write-protected state. 

F2 The subsystem release diskette. The SUBMIT file reads 

libraries and INCLUDE files from this diskette, but does not 
modify the diskette in any way. 

F3 A temporary and listing diskette. The SUBMIT file writes all 
intermediate files (such as link files) to this diskette and 
deletes them when it no longer needs them. It also writes 
all listing files, link maps, and locate maps to this 
diskette. 



If you do not have a four-drive development system, or if your drives are 
set up with different disk mnemonics, you must modify the subsystem 
SUBMIT files and the subsystem configuration files to accomodate this. 



Using a Series III Development System 

If you use a Series III Microcomputer Development System in your 
configuration process, your versions of PLM86, ASM86, LINK86; and LOC86 
run under 8086 execution mode. Thus you will have to modify the 
configuration files and SUBMIT files in order to make them run correctly 
on your development system. Use the following guidelines when making 
these modifications. 



4-10 



LOCATING A TEST AND DEVELOPMENT SYSTEM IN RAM 



Guidelines for Configuration Files 

• Ensure that each assembly language configuration file (a file 
whose name is of the form "file.A86" ) contains the NAME 
directive. This directive has the form: 

NAME modname 

where modname is the name of your module. The one restriction on 
modname is that it must be different from all other modname 
values in the linked system. Place this NAME directive at the 
beginning of the file. Refer to the 8086/8087/8088 MACRO 
ASSEMBLY LANGUAGE REFERENCE MANUAL FOR 8086-BASED DEVELOPMENT 
SYSTEMS for more information concerning the NAME directive. 



Guidelines for SUBMIT Files 

• For each SUBMIT file (files whose names are of the form 
"file.CSD"), add RUN before each ASM86, PLM86, LINK86, and LOC86 
command or put a RUN/EXIT pair around every set of ASM86, PLM86, 
LINK86, and LOC86 commands. Refer to the INTELLEC SERIES III 
MICROCOMPUTER DEVELOPMENT SYSTEM CONSOLE OPERATING INSTRUCTIONS 
for more information about the RUN and EXIT commands. 

• Add the NOINITCODE control to every L0C86 command in your SUBMIT 
files. Refer to the iAPX 86,88 FAMILY UTILITIES USER'S GUIDE FOR 
8086-BASED DEVELOPMENT SYSTEMS for more information about this 
control. 

• Remove the DATE control from every ASM86 and PLM86 statement. In 
most cases, this means that you will also be removing one of the 
formal parameters from the SUBMIT file. Therefore, when you 
invoke the SUBMIT file, do not specify the date parameter, but 
include the comma (,) as a placeholder. 

• Remove the MACRO control from the ASM86 statements in all SUBMIT 
files. 



LINKING AND LOCATING APPLICATION JOBS 

The most common method of linking and locating your application jobs is 
to link the first-level job together with every job ultimately created by 
that first-level job and one or more interface libraries. You must then 
locate this module at an absolute address. Figure 4-5 illustrates this 
link and locate procedure. 
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FIRST-LEVEL JOB 
OBJECT CODE 


















OFFSPRING JOB 
OBJECT CODE 








INTERFACE 
LIBRARY 








• 
• 
• 






• 
• 
• 


OFFSPRING JOB 
OBJECT CODE 






INTERFACE 
LIBRARY 















LINKED APPLICATION 
FIRST-LEVEL JOB 



LOC86 



LOCATED APPLICATION 
FIRST-LEVEL JOB 



Figure 4-5. Application Job Link and Locate Procedure 



If you do not link your first-level jobs together with their offspring 
jobs, you should link and locate the offspring jobs first. By doing 
this, you can obtain the absolute starting locations of the offspring 
tasks from the locate maps and specify these values in the CREATE$JOB and 
CREATE$TASK calls of their parent tasks before compiling the parents. 

The following sections describe the individual link and locate commands 
in more detail, and describe the interface libraries. The guidelines 
discussed in the "Using a Series III Development System" section of this 
chapter also apply to these link and locate commands. 
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Linking Application Jobs 

The LINK86 command is used to link your application jobs. This command 
is described in detail in the appropriate iAPX 86,88 FAMILY UTILITIES 
USER'S GUIDE. However, the format of the LINK86 command that you must 
enter is: 

LINK86 & 

:fx:app_job.obj, & 

:fx: interface. lib & 

TO :fx:app_job.lnk MAP PRINT( : fx:app_job.mpl) 



where: 



fx The appropriate disk mnemonic, indicating where the 

file resides. 

app_job.obj Object code for your application job. You do not need 
to provide this code on one file; you can link in 
several files or libraries at this point. 

interface. lib Interface libraries for the subsystems that your jobs 
make use of. You may have to link in several 
libraries at this point. These interface libraries 
are described in later paragraphs of this section. 

app_job.lnk Name of the file in which LINK86 places the module 
containing your linked application code. Use this 
file as the input file when locating your application 
job. 

app_job.mpl Name of the file in which LINK86 writes the link map 
for the application job. 



During the link process, you must link in a number of interface 
libraries. These libraries contain the routines that satisfy external 
references to system calls that you make in your application code. The 
number and names of the libraries that you must link in with your 
application code depend on which subsystems your jobs use and which model 
of PL/M-86 computation the jobs were compiled under. Table 4-1 shows the 
correlation between subsystems, models of computation, and interface 
libraries. Specify these libraries as the last modules in the LINK86 
input list so that they can satisfy references from all linked modules. 
Notice that no library exists for the small model of PL/M-86 computation; 
the iRMX 86 Operating System does not support applications compiled in 
small. 
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Table 4-1. Interface Libraries as a Function of PL/M-86 
Models and Subsystems 





COMPACT 


LARGE OR MEDIUM 


Nucleus 


RPIFC.LIB 


RPIFL.LIB 


Basic I/O System 


IPIFC.LIB 


IPIFL.LIB 


Application Loader 


LPIFC.LIB 


LPIFL.LIB 


Extended I/O System 


EPIFC.LIB 


EPIFL.LIB 


Human Interface 


HPIFC.LIB 


HPIFL.LIB 



Locating Application Jobs 

After you have used LINK86 to generate a link module for your application 
job, you must use LOC86 to bind this link module to absolute addresses. 
The appropriate iAPX 86,88 FAMILY UTILITIES USER'S GUIDE contains 
specific instructions on the use of the LOC86 command. 

Since you are laying out your test system by job rather than by class, 
use a combination of the ORDER and ADDRESSES controls on L0C86 to 
simplify the location process. Use the ORDER control to declare the 
order in which the classes of the job are to be located. Then declare 
the absolute address of the code class with the ADDRESSES control. LOC86 
automatically locates the rest of the classes following the code class. 
If you do this, a call to L0C86 appears similar to the following: 



LOC86 input_file TO output_file & 

ORDER (CLASSES (CODE, DATA, STACK, MEMORY)) & 

SEGSIZE (STACK (stack_size)) & 

ADDRESSES (CLASSES (CODE (absolute_address))) & 

MAP PRINT (map_file) & 

OBJECTCONTROLS (NOLINES,NOCOMMENTS,NOPUBLICS, & 
NO SYMBOLS) 



where: 

input_f ile 
output file 



Name of link file produced previously by LINK86. 

Name of the file in which LOC86 writes the absolute 
module. 
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stack_size Size of this job's stack. Use this control for 

those jobs requiring a statically allocated stack. 
A stack is statically allocated if you, and not the 
Operating System, specify a stack location and 
size. A minimum value of 200H should be specified, 
if this control is required; otherwise specify 
zero. It is recommended that you specify zero for 
this parameter and let the Nucleus dynamically 
allocate a stack whenever possible. This depends, 
however, on the model of PL/M-86 computation that 
you used when compiling your code. With 
dynamically allocated stacks, you specify the stack 
size in the %JOB macro call. Refer to the "%JOB 
Macro" section of this chapter for further 
information. 

absolute_address Absolute starting location of the code segment of 

the job. You can obtain this address by examining 
the locate map of the previously located module. 
Refer to the next section of this chapter for 
further information about determining absolute 
addresses. 

map_f ile Name of the file in which LOC86 writes the locate 
map. Always generate the locate map. You need it 
in order to determine where to locate the next 
module. It also contains information that you need 
in order to generate the configuration file (as 
described in the "Build the Configuration File" 
section of this chapter). 



Use this form of the LOC86 command to locate each application job. 



THE ITERATIVE LINK AND LOCATE PROCESS 

As mentioned before, the link and locate process is an iterative 
process. You must link and locate one job, examine its locate map to 
determine its ending address, and use that information to link and locate 
the next job. This process can be broken down into the following steps: 

1. Link and locate the Nucleus first by submitting the NUCLUS.CSD 
SUBMIT file (described in Chapter 6). A parameter to this SUBMIT 
file is used to assign the Nucleus to absolute memory locations. 
Specify the lowest available memory locations for the Nucleus 
(1C00 or 2000, depending on the type of device, if you are using 
the Bootstrap Loader to load your system into memory; 800 if you 
are using the iSBC 957A package; or 400 otherwise). 

2. Determine the ending address of the Nucleus from the locate map 
generated by LOC86. Record this value in the memory map. 
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3. Using the next available address as input to a subsystem SUBMIT 
file (described in Chapters 7 through 13), link and locate the 
next subsystem. 

4. Determine the starting and ending addresses from the locate map. 
Record these values in the memory map. Also record the entry 
point address and data segment base in the leftmost column. You 
will use these values later when creating the configuration file. 

5. Go back to step 3 and continue until you have linked and located 
all of the subsystems. 

6. Use the next available address as the starting address for the 
root job. You do not have to link or locate the root job at this 
point. Instead, assume a length of 600H bytes for it and leave 
that amount of space. (This length is adequate for an 
application system with approximately 20 first-level jobs. If 
your system contains more than 20 first-level jobs, you should 
allow more space for the root job.) Record the starting and 
ending addresses on the memory map. 

7. Using the next available address as input to the ADDRESSES 
control of the LOC86 command, link and locate the first 
application job. 

8. Determine the starting address, the ending address, the entry 
point address, and the data segment base from the locate map and 
record these values in the memory map. 

9. Instead of using the next available address as input to the 
ADDRESSES control, leave some space between application jobs so 
that these jobs can grow during the debugging process, if 
needed. Use your own judgement as to how much space to leave, 
but if you are unsure, leave approximately IK bytes for growth. 
Add this padding factor to the ending address of the previously 
located module and record that figure as the starting address of 
the next module. 

10. Using the starting address recorded on the memory map as input to 
the ADDRESSES control of LOC86, link and locate the next 
application job. 

11. Go back to step 8 and continue until you have located all 
application jobs. 



After you perform this procedure once, you can create an additional 
SUBMIT file to locate all of the modules at once. This procedure can 
contain LINK86 commands for those jobs that may have to be relinked. The 
padding factors that you included when assigning memory locations allow 
the modules to grow during the debugging process without affecting the 
LOC86 commands used to locate them. 
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NOTE 



The locate map for the Nucleus always 
contains a warning message similar to 
the one shown in the following 
example. This is a normal message for 
the Nucleus. It does not indicate 
errors in the LOC86 command. 



Example: 

This example assembles the Nucleus configuration file, links and locates 
the full Nucleus, and records values from the locate map in the memory 
map worksheet. It makes the following assumptions about the system: 

• Disk drive FO on the INTELLEC Series II Development System is a 
system disk containing LOC86. 

• Disk drive Fl contains the user's configuration diskette. This 
diskette contains a copy of the Nucleus SUBMIT file NUCLUS.CSD. 

• Disk drive F2 contains the Nucleus release diskette. 

• Disk drive F3 contains a diskette on which the SUBMIT file can 
place temporary and intermediate files. 

• The Nucleus is going to be located at address 1C00H. 



The following command calls a SUBMIT file to assemble the Nucleus 
configuration file and link and locate the Nucleus. Refer to Chapter 6 
for a complete description of the SUBMIT file. 

SUBMIT :F1:NUCLUS (04-01-81, 1C00H) 

The located object module is written to file NUCLUS on drive Fl and the 
locate map to file NUCLUS. MP2 on drive F3. Figure 4-6 shows a part of 
this locate map. This map should be viewed as an example only. It may 
differ from the one generated when you locate the Nucleus. 
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ISIS-II MCS-86 LOCATFR, VI. 3 INVOKED BY: 
LOC86 ft 

it 3:nuclus.InK TO ;fi:nuclus ft 
MAP PRINT(:f 3:nuclus.mD2) ft 

NOLINES NOCOWMFtfTS NOSYMBOLS ft 

SEGSIZECstack(O)) ft 

ORDEP(classes(code, data)) ft 

ADDRESSES (classes ( co^eC 01 COOH))) 
WARNING 26: DECREASING SIZE OF. SEGMENT 
SEGMENT: STACK 

SYMBOL TABLE OF MODULE NBEGIN 
READ FROM FILE :Fi : wUCLUS.LNK 
WRITTEN TO FILE :F1:NUCLUS 



BASE OFFSET TYPE SYMBOL 
01COH OOOOH PUB NBEGIN 



BASE 



OFFSET TYPE SYMBOL 



MEMORY MAP OF MODULE NBEGIN 
READ FROM FILE : Fi : NUCLUS .LNK 
WRITTEN TO FILE :F1:NUCLUS 

SEGMENT MAP 



START 



STOP 



LENGTH ALIGN NAME 



CLASS 



OQOOOH 


003FFH 


0400H 


A 


(ABSOLUTE) 




OICOOH 


07A79H 


5E7AH 


W 


CODE 


CODE 


07A7AH 


07A93H 


OOlAH 


W 


OBJ-SEG 


CODE 


07A94H 


07A9UH 


OOOAH 


w 


v)OB_SEG 


CODE 


07A9EH 


07AB1H 


0014H 


w 


TASK-SEG 


CODE 


07A62H 


07AB9H 


O008H 


w 


MB.SEG 


CODE 


07ABAH 


07AC1H 


OOOgH 


w 


SEM.SEG 


CODE 


07AC2H 


07ACBH 


OOOAH 


w 


REG-SEG 


CODE 


07ACCH 


07AD9H 


OOOEH 


w 


FS_SEG 


CODE 


07ADAH 


07AF3H 


OOlAH 


w 


TNT.SEG 


CODE 


07AF4H 


07AF9H 


OOObH 


w 


EXCEP-SEG 


CODE 


07AFAH 


07b29H 


0030H 


w 


VALID_S£G 


CODE 


07B2AH 


07B2EH 


00 5H 


w 


PIC-CNF.SEG 


CODE 


07B30H 


07B41H 


0012H 


w 


_IMR_P0RT 


CODE 


07B42H 


07B53H 


0012H 


w 


_E01„PORT 


CODE 


07B54H 


07B65H 


0012H 


w 


_ISR_READ_PORT 


CODE 


07B66H 


07B6EH 


0009H 


8 


.PIC-INFO'. 


CODE 


07B6FH 


07B7BH 


QQOAH 


B 


TIMER-.CNF.SEG 


CODE 


07B7An 


07B7AM 


OOOOH 


w 


CSEG 


CODE 


07B7AH 


07B7SH 


0002H 


w 


SLAVE-SEG 


CODE 


07B7CH 


07DE3H 


0268H 


w 


DATA 


DATA 


07DFOh 


07DFBH 


OOOCH 


G 


READYLISTROOT_ 
-DATA 


DATA 


07DFCH 


07EF8H 


OiOOH 


w 


KSTACK 


DATA 




Figure 


4-6. Example 


Nucleus Locate Map 
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07FOOH 


07F0DH 


OQOEH 


G 


PELAYLISTROOT_ 
-DATA 


DATA 


07F10H 


07F61H 


0052H 


G 


IDLE.TASK.DAIA 


DATA 


07F70H 


07F7FH 


0010H 


G 


INTVEC-REG.SEG 


DATA 


07F80H 


07F8FH 


O010H 


G 


EXT„REG_SEG 


DATA 


07F90H 


07F9FH 


0010H 


G 


JOB_REG..SEG 


DATA 


0/FAOH 


07MFH 


0010H 


G 


SEM-REG_SbG 


DATA 


07FBOH 


07FPFH 


0010H 


G 


MAlL.REG.bEG 


DATA 


07FC0H 


07FCFH 


0010H 


G 


OD_REG_SEG 


DATA 


07FD0H 


07FHFH 


0010H 


G 


PQOL.REG_SEG 


DATA 


07FEOri 


07FFFH 


0010H 


G 


DELLT10N.RFG-.S 
-EG 
71SEC, 


DATA 


07FF0H 


07FFFH 


0010H 


G 




08000H 


08000H 


OOOOH 


G 


LIB-.87-PUB 




08O00H 


08003H 


0004H 


G 


LIB-.R7-1W1T 




08004b 


08004H 


OOOOH 


W 


STACK 


STACK 


08010H 


0813BH 


012CH 


G 


I6TACK 


STACK 


0813CH 


0813CH 


OOOOH 


W 


MEMURY 


MEMORY 



GROUP MAP 

ADDRESS GPQHp OR SEGMENT NAME 
07370H DGROUP 

DATA 

READYMSTPOOT^DATA 

KSTACK 

DELAtfLISTPQOT-DATA 

idletask.data 

ISTACK 

INTVEC^REG-SEG 
EXT-RFG-SEG 
JHB_REG_SEG 
SEM-REG-SEG 
MAiL^PEG^SEG 
OD.REG.SEG 
POUT._REG_SEC 
DELETIJN-PEG.SEG 
01C00H CGRHUP 
CODE 
UBJ.SEG 
JOB-SEG 
TAbK.SEG 
HB-SEG 
SEin_SEG 
REG.SEG 
FS_SEG 
iMT.SEG 
EXCFP_SFG 
VALID-SEG 



Figure 4-6. Example Nucleus Locate Map (continued) 
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PICCNF_iSFG 
..ImR-PORT 

_f:gt_port 
.tsr.read.poht 

_PIC_TftFO 
TIMFR.CNF^SE'G 

SLAVe.SEG 



Figure 4-6. Example Nucleus Locate Map (continued) 



Notice the warning message contained on the locate map. This is a normal 
message that always occurs when you locate the Nucleus. Do not be 
alarmed by it. It does not indicate an error. 

As you can see from arrow A in Figure 4-6, the next available memory 
location is 8DF:0. The last location used by the Nucleus is 8DE:F. The 
memory map shown in Figure 4-7 contains these values. 
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iRMX 86 w SYSTEM MEMORY MAP WORKSHEET 



Configuration file name: 

Start address/ 
Data segment base 



Module 



Length 



Absolute 
Address 



(reserved) 



reset vector 



Highest RAM address 



Application Job 



Root Job 



Debugger 



Nucleus 



Interrupt vector 



< 



< 
< 
< 
< 
< 
< 
< 
< 



FFFF : F 

FFFF : 
1FFF:F 



8DF:0 



< 
< 
< 
< 
< — 

^s 8DE:F 
s^ 1C0:0 



< — 

/ 40:0 

< 



0:0 



Figure 4-7. Entering the Nucleus End Address on the Memory Map 
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BUILD THE CONFIGURATION FILE 

After you have created the memory map and located the jobs, you are ready 
to build the system configuration file or modify one of the existing 
files provided on the subsystem release diskettes. The system 
configuration file is an assembly language source file which must 
describe each first-level job, the system address blocks, and the system 
as a whole. The file must provide this information in the form of macro 
calls. The macros used in the configuration file are: 

%JOB 
%SAB 
% SYSTEM 

These macros are described individually in the remainder of this 
section. However, the following instructions apply to the configuration 
file as a whole and to all of the macros. 

• In addition to placing macros in your system configuration file, 
you must also include two other statements. The first statement 
in your system configuration file must be an $INCLUDE statement 
to include the file CTABLE.MAC in the assembly of your 
configuration file. CTABLE.MAC is on the Nucleus release 
diskette and contains the definitions of the macros used in the 
remainder of the configuration file. The format of this 
statement is: 

$ I NCLUDE ( : f x : CTABLE . MAC ) 

where fx is the identifier of the drive containing the Nucleus 
release diskette. 

The last statement in your configuration file must be the END 
statement. The format of this statement is: 

END 



• You can include space characters anywhere within your macro 
calls, in order to provide a more readable configuration file. 
Space characters consist of blank spaces. 

• You can spread your macro calls over several lines (such as 
placing one parameter on a line) if you specify the comment macro 
(% f ) on each line that is continued. An example of this is: 

%SAB (05000, %' start base 
OFFFF, %' end base 
U) 

You must use these comment macros in order to exclude the 
carriage return and line feed characters from being processed by 
the assembler. 
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• For certain parameters you must specify a value of type addr, 
offset, or base. These are described as follows: 

addr An absolute address in the form base: offset. 

base An absolute paragraph address. 

offset A value which is offset from the specified base. 

You must supply these values exactly as they appear on the locate map 
produced by LOC86. The required radix for each of these values is 
hexadecimal. Therefore, do not include the suffix H when specifying 
a value. For other parameter types (such as byte or word), you must 
explicitly specify a radix, with decimal the assumed default. 



%JOB MACRO 

The %JOB macro is used to specify parameters for first-level jobs. You 
must specify one %JOB macro for each optional subsystem first-level job 
and each application first-level job. Figure 4-8 contains the format of 
the %JOB macro. It is a worksheet that you can use to prepare the macro 
calls. The values in parentheses are suggested values. Use these 
suggested values for noncritical parameters. 
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Macro call: JOB (defines 


first- 


-level jobs) 






Number of calls required: 




one 


for each 


first-level job 


CONFIGURATION FILE NAME: 




FORMAT: 

parameter 

%JOB (directory size, 
pool min, 
pool max, 
max objects, 
max tasks, 
max task priority, 
exception handler entry, 
exception handler mode, 
job_flags, 
init task priority, 
init task entry, 
data segment base, 
stack pointer, 
stack size, 
task flags) 




type 

word 
word 
word 
word 
word 
byte 
addr 
byte 
word 
byte 
addr 
base 
addr 
word 
word 




suggested 
default 

(0) 

(OFFFFH) 

(OFFFFH) 

(OFFFFH) 

(0) 

(0:0) 

(1) 
(0) 
(0) 

(0) 
(0:0) 
(512) 

(0) 


value 
































NOTES: 

1. Type addr is specified as base:offset. 

2. Types addr and base must be entered as hexadecimal 
without the suffix H. Types word and byte default 
but will accept all radix suffixes. 


numbers 

to decimal, 



Figure 4-8. %J0B Macro Worksheet 
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As you can see from Figure 4-8, the format of the %JOB macro is almost 
the same as the format of the CREATE$JOB system call described in the 
iRMX 86 NUCLEUS REFERENCE MANUAL. The only difference between the two is 
that the %JOB macro omits the param$obj parameter and includes the 
except ion_handler_entry and except ion__handler__mode parameters in line, 
rather than as a pointer to a structure containing this data. The other 
parameters are the same. For completeness, a short description of each 
of the parameters of the %JOB macro follows. For more detailed 
information, refer to the description of the CREATE$JOB system call in 
the iRMX 86 NUCLEUS REFERENCE MANUAL. 



directory size 



pool_min 
pool_max 
max objects 



Maximum allowable number of entries 
in this job's object directory. A value of 
zero indicates that no directory is to be 
created. The maximum value for this 
parameter is OFFOH. 

Minimum allowable size of the job's memory 
pool, in 16-byte paragraphs. 

Maximum allowable size of the job's memory 
pool, in 16-byte paragraphs. 

Maximum number of objects that can exist 
simultaneously in the job. A value of 
OFFFFH indicates unlimited objects. 



max tasks 



Maximum number of tasks that can exist 
simultaneously in the job. A value of 
OFFFFH indicates unlimited tasks. 



max task priority 



Maximum allowable priority of tasks in the 
job. Specify a value in the range to 255 
decimal. A value of zero indicates that the 
priority of the root task is the maximum 
allowable. 



exception handler entry 



Pointer to the start address of the job's 
exception handler. A value of 0:0 indicates 
that the job uses the exception handler 
specified in the %SYSTEM macro (described 
later in this chapter). 



exception handler mode 



Encoded indication of the job's exception 
mode. Values are interpreted as follows: 



value 

1 
2 
3 



Pass control to 

exception handler 

Never 

On programming error conditions only 

On environmental conditions only 

On all exceptional conditions 
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job flags 



Information that the Nucleus needs to create 
and maintain the job. Bits in this word are 
interpreted as follows: 



bit 
15-2 



meaning 
Reserved. 



If set to 0, the Nucleus validates 
parameters for all system calls made 
by tasks in this job or its 
offspring. Refer to the "Parameter 
Validation" section of Chapter 6 for a 
further discussion of parameter 
validation. 

If set to 1 , the Nucleus does not 
validate parameters for tasks in this 
job. 

Reserved. 



init task priority 



init_task_entry 
da ta_s egme nt_bas e 

stack pointer 



Priority of this job's initialization task. 
A value of zero assigns the initialization 
task a priority equal to the max_job_priority 
parameter. 

Entry point of this job's initialization task. 

Base value of the initialization task's data 
segment. A value of zero indicates that the 
task itself assigns the data segment. 

Address of the initialization task's stack. 
A value of 0:0 causes the Nucleus to allocate 
a stack segment to the task and initialize 
the SS register to the base address of this 
segment and the SP register to the value of 
the stack_size parameter. It is recommended 
that you specify 0:0 for this parameter. 
This permits dynamic stack allocation and 
deallocation. 



stack size 



Size in bytes of the initialization task's 
stack segment. Specify 200H as a minimum 
value for this parameter. You must enter a 
value for this parameter even if the job uses 
dynamically allocated stacks. 
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task_flags Information that the Nucleus needs to create 

and maintain the job's initial task. Bits in 
this word are interpreted as follows: 

bit meaning 

15-1 Reserved bits which should be set to 
zero. 

If one, the initial task contains 
floating-point instructions which 
require the 8087 NDP for execution. 

If zero, the initial task contains no 
floating point instructions. 



For your PL/M-86 jobs, the parameters that you must specify for each %J0B 
macro depend on the PL/M-86 size control. The following sections outline 
the differences with references to the appropriate %J0B macro parameters. 



Data Segment Allocation 

PL/M-86 large model procedures . Large model procedures have statically 
allocated data segments. However, you do not have to specify data 
segment values because the PL/M-86 compiler generates code that 
automatically initializes the data segment (DS) register for each 
procedure when that procedure begins executing. Therefore, for large 
model procedures, set the data segment base parameter to zero. 



PL/M-86 medium and compact model procedures . These procedures also have 
statically allocated data segments. However, the compiler does not 
automatically initialize the data segment register for medium and compact 
models of computation. Therefore, if you compile a procedure using 
either of these models, you must specify the base address of that 
module's DGROUP as the data_segment parameter of the %J0B macro. Obtain 
the base address from the locate map produced by L0C86. (DGROUP includes 
the data, stack, and memory segments /classes for the medium model and the 
data segment/class for the compact model. The constant segment/class is 
included in CGROUP if the ROM compiler control is used.) 



Stack Allocation 

PL/M-86 large and compact models . The Operating System must dynamically 
allocate stacks for procedures compiled in these models. Thus, you must 
specify 0:0 for the stack_pointer parameter of the %J0B macro. The 
Operating System allocates a stack to the job with a size that you 
specify in the stack size parameter of the %J0B macro. 
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When you use LOC86 to locate these procedures, you must use the SEGSIZE( 
STACK(O)) control. Refer to "The Locating Application Jobs" section of 
this chapter for further information about this control. 



PL/M-86 medium models . Procedures compiled using the medium model 
require statically allocated stacks. Thus, for these procedures, you 
must specify the address of the stack in the stack_pointer parameter of 
the %JOB macro. Use the value indicated in the locate map when 
specifying this parameter. You should also specify the size of the stack 
in the stackjsize parameter of the %JOB macro. Use the same size as you 
specified in the SEGSIZE( STACK( ... ) control of the LOC86 command. 
Refer to "The Locating Application Jobs" section of this chapter for 
further information concerning the LOC86 command. 



%SAB MACRO 

The %SAB macro declares the size and location of each system address 
block. A system address block is an area of addressable memory not 
available as dynamically reusable memory. This includes ROM, nonexistent 
memory, and RAM reserved for jobs. The Nucleus needs to know where these 
reserved areas are so that it does not reassign them. Look at the memory 
map worksheet that you filled out for your system and use %SAB macro 
calls to reserve all memory needed for the Nucleus, subsystems, 
application jobs, interrupt vector, reset vector, iSBC 957A workspace, 
and ROM. 

The format of the %SAB macro is shown in Figure 4-9. This figure is a 
worksheet that you can use to prepare the macro calls. 
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Macro 

Number 

CONFIG 


call: SAB (for 


system address 


blocks) 


of calls required: 


one or more 




ORATION FILE NAME: 












FORMAT 
%SAB 


parameter 

(start base, 
end base, 
type) 


type 

base 
base 

see note 
1 


suggested 
default value 




U 




%SAB 


(start base, 
end base, 
type) 


base 
base 

see note 
1 






U 




%SAB 


(start base, 
end base, 
type) 


base 
base 

see note 
1 






u 




NOTES : 
1. 

2. 

3. 


The type parameter is reserved for future use. Enter the 
character U for this parameter. 

A SAB is declared between start base:0 and end base:F, 
inclusive. 

Types addr and base must be entered as hexadecimal numbers 
without the suffix H. Types word and byte default to decimal 
but will accept all radix suffixes. 



Figure 4-9. %SAB Macro Worksheet 
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The parameter of the %SAB macro are described as follows: 



start_base A base value that defines the beginning of the 

SAB. The starting address of the SAB is 
interpreted as start_base:0. 

end_base A base value that defines the end of the SAB. The 

end address of the SAB is interpreted as 
end_base:F. 

type Reserved for future use. Enter the character U 

for this parameter. 

When placing %SAB macro calls in the system configuration file, you must 
observe the following guidelines: 

• You must order your %SAB macro calls by the start addresses of 
the memory that they declare (from smallest to largest). 

• You must declare the interrupt vector as a system address block 
with a %SAB call. 

• You must make %SAB calls for all ROM in your system. 

• You must not overlap system address blocks (that is, %SAB macro 
calls must declare discrete areas of memory). 

• Each block of memory not declared with a %SAB macro call must be 
at least (minimum transfer size +48 decimal bytes) in length. 
Refer to the "%SYSTEM Macro" section of this chapter for a 
description of the minimum transfer size. 

• The first block of memory not declared with a %SAB macro call 
must be at least 160 decimal bytes long. 



% SYSTEM MACRO 

The %SYSTEM macro is used to declare parameters that affect the system as 
a whole. You must declare exactly one %SYSTEM macro for your entire 
system and place it immediately prior to the END statement in the system 
configuration file. Figure 4-10 contains the format of the %SYSTEM 
macro. This figure is a worksheet that you can use to prepare the macro 
call. The values in parentheses are suggested values. Use these 
suggested values for noncritical parameters. 
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Macro c 

Number 

CONFIGU 


all: SYSTEM (system parameters) 


of calls required: exactly one 




RATION FILE NAME 




FORMAT: 




suggested 




parameter type 


default value 


% SYSTEM 


(nucleus_entry, base 
rod size, word 
min trans size, word 
debugger, see note 

1 
default e h provided, see note 

2 




(30) 


(64) 


(A) 


(N) 






exception mode) word 




NOTES: 






1. 


Valid entries for the debugger parameter include: 




A Debugger available 






N No debugger available 




2. 


Valid entries for the default e h provided parameter include: 




Y Yes 






D Debugger 






N No 




3. 


Types addr and base must be entered as hexadecimal numbers 




without the suffix H. Types word and 


byte default to 




decimal, but will accept all radix suffixes. 



Figure 4-10. %SYSTEM Macro Worksheet 
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The parameters of the %SYSTEM macro are described as follows: 



nucleus entry 



rod size 



min trans size 



debugger 



Base value of the code segment of the Nucleus. 
For this parameter, specify the base portion of 
the value shown on the Nucleus locate map. 

Maximum number of objects that can be cataloged 
in the root object directory. 

Minimum amount of memory, in 16-byte paragraphs, 
that the Nucleus allows to be transferred 
between jobs. If your application programs 
consistently request memory in larger than 
64-paragraph blocks, you should adjust this 
parameter to reflect this, in order to cut down 
on system overhead involved with transferring 
memory. However, do not specify a value much 
larger than the amount of memory your programs 
ordinarily request or memory fragmentation will 
occur, and the additional memory will be wasted. 

Letter that indicates whether or not the 
Debugger is available. Possible values include: 



A The Debugger is available. 

N No Debugger is available. 

default_e_h_provided Letter that indicates the system default 

exception handler. Possible values include: 

Y A user-supplied exception handler is 
the system default. 



N 



The Debugger is the system default 
exception handler. 

No default exception handler is 
specified. 



If you specify Y for this parameter, you must 
create your own exception handler, designate it 
to be a public procedure having name RQSYSEX, 
and link it to the root job. If you specify D 
for this parameter, make sure to include the 
Debugger in your system. Even if you include 
the Debugger in your system, you do not have to 
specify it as the system default exception 
handler. 



4-32 



LOCATING A TEST AND DEVELOPMENT SYSTEM IN RAM 



mode Encoded indication of the exception handler 

mode. Values are interpreted as follows: 

Pass control to 
value exception handler 

Never 

1 On programming error conditions 

only 

2 On environmental conditions only 

3 On all exceptional conditions 



MACRO PARAMETERS FOR SUBSYSTEMS 

Tables 4-2 and 4-3 list parameter values for the %JOB and %SYSTEM calls 
which you should use, depending on the subsystems in your application 
system. These tables list recommended values. A blank entry in either 
of the tables implies that you must determine this value. Notes for 
these tables follow the tables. 

Notice that Tables 4-2 and 4-3 contain no entries for the Human 
Interface. You do not specify a %JOB macro for the Human Interface in 
order to include it in your application system. Instead, you must 
include the Human Interface as an I/O job during the configuration of the 
Extended I/O System. Refer to Chapters 12 and 13 for further information. 
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Table 4-2. Suggested % JOB Values for Optional Subsystems 



Macro 


Parameter 


Debugger 
Value 


Terminal Handler 
Value 


I/O System 
Value 


%JOB 


directory size 











pool min 


17 OH (without 
NDP support) 

178H (with NDP 
support) 


85H 


500H 


pool max 


OFFFFH 


OFFFFH 


500H 


max objects 


OFFFFH 


OFFFFH 


OFFFFH 


max tasks 


OFFFFH 


OFFFFH 


OFFFFH 


max job priority 











exception hand- 
ler entry 


0:0 


0:0 


0:0 


exception hand- 
ler mode 











job flags 











init task pri- 
ority 








128 


init__task entry 


note 1 


note 1 


note 1 


data segment 
base 











stack pointer 


0:0 


0:0 


0:0 


stack size 


300H 


300H 


200H 


task flags 


(without 
NDP support) 

1 (with NDP 
support ) 
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Table 4-2. Suggested %JOB Values for Optional Subsystems 

(continued) 



Macro 


Parameter 


Application 
Loader 
Value 


Extended 1/0 
System 
Value 


%JOB 


directory size 








pool min 


20H 


180H 


pool max 


20H 


180H 


max objects 


50 


0FFFFH 


max tasks 


5 


0FFFFH 


max job priority 








exception hand- 
ler entry 


0:0 


0:0 


exception hand- 
ler mode 








job flags 








init task pri- 
ority 


130 


140 


init task entry 


note 1 


note 1 


data segment 
base 








stack pointer 


0:0 


0:0 


stack size 


160 


300H 


task flags 









4-35 



LOCATING A TEST AND DEVELOPMENT SYSTEM IN RAM 



Table 4-3. Suggested %SYSTEM Values for Optional Subsystems 



Macro 


Parameter 


Debugger 
Value 


Terminal 

Handler 

Value 


I/O System 
Value 


% SYSTEM 


nucleus entry 


note 2 


note 2 


note 2 


rod size 


30 


30 


30 


min trans size 


40H 


40H 


40H 


debugger 


A 


note 3 


note 3 


default e h 
provided 


D 


note 3 


note 3 


mode 


3 


note 4 


note 4 


Macro 


Parameter 


Application 
Loader 
Value 


Extended I/O 
System 
Value 




%SYSTEM 


nucleus entry 


note 2 


note 2 




rod size 


30 


30 




min trans size 


40H 


40H 




debugger 


note 3 


note 3 




default e h 
provided 


note 3 


note 3 




mode 


note 4 


note 4 
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NOTES FOR TABLES 4-2 AND 4-3: 

1. Determine the values of the initialization task entry points from 
the absolute address specified as input to L0C86 (or the SUBMIT 
file used to locate the subsystem) . The base portion of this 
address is the base of the entry point. The offset portion of 
the entry point is 0. Thus the entry points for all subsystems 
are of the form "base:0". 

2. Determine this value from the Nucleus locate map. Use the base 
portion of the code class start address. 

3. These values vary depending on whether you include the Debugger 
in your application system. 

4. These values vary depending on which exceptions are to be handled 
by the exception handler. 



CREATING THE CONFIGURATION FILE 

After you have filled out all of the necessary %J0B, %SAB, and %SYSTEM 
worksheets, use a text editor to build one file containing all of these 
macro calls. You can create an entirely new file or use one of the files 
available on the release diskettes. Each optional subsystem release 
diskette contains an example system configuration file. This file is 
named xROOT.A86, where x indicates the subsystem with which it is 
associated (for example, IROOT.A86 is contained on the I/O System release 
diskette and LROOT.A86 on the Application Loader release diskette). Each 
one of these files contains %J0B calls for that particular subsystem and 
all other required subsystems, %SAB calls, and a %SYSTEM call. You can 
use any of these example system configuration files as your system 
configuration file by filling in the absolute addresses, adding %J0B 
calls for your application jobs, and modifying the %SAB calls to reflect 
your hardware environment. 

After you create or modify your system configuration file, write its name 
on the macro worksheets, because you must specify this name later, during 
the root job generation process. 

When creating or modifying your system configuration file, remember the 
following things: 

• Place an $INCLUDE statement for the file CTABLE.MAC as the first 
statement of the file and the END statement as the last statement 
of the file. 

• Enter all of the %J0B, %SAB, and %SYSTEM macro calls into this 
file. You can enter them in the same format as shown on the 
worksheets if you place comment macros (%') at the end of each 
continued line, or you can place the parameters for each macro 
call on a single line. Enter the required %SAB calls for your 
system, a %J0B call for each first-level job, and one %SYSTEM 
call. Place the %SYSTEM macro call immediately before the END 
statement. It must be the last macro call. 
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• It does not matter whether you place %JOB or %SAB calls first in 
the file. However, the order in which you enter the individual 
%JOB and %SAB calls is important. The %SAB calls must abide by 
the order restrictions described in the "%SAB Macro" section of 
this chapter. The %JOB call order is important because the root 
job initializes jobs in the order that their %JOB calls appear in 
the system configuration file. Always place the %JOB calls in 
the following order: 

1. Subsystem first-level jobs, in the following order: 

Terminal Handler and/or Debugger (in any order) 
Basic I/O System 
Application Loader 
Extended I/O System 

You can omit the Application Loader and still include the 
Extended I/O System. However, if you include the Human 
Interface as an I/O job during Extended I/O System 
configuration (refer to Chapters 12 and 13), you must 
include the Application Loader and place its %JOB macro in 
the indicated position. 

2. Application first-level jobs 

Place the subsystem first-level %JOB calls first so that the 
services of the subsystems are available to the remainder of the 
first-level jobs when the first-level jobs are initialized. 

The order in which you place %JOB calls for your application jobs 
depends on the content of these jobs. Any job whose services are 
immediately used by other jobs should be initialized before the 
other jobs; thus you should place its %JOB call earlier in the 
file. 

After you have created the configuration file or modified one of the 
existing ones, you can go on to the next section and generate the root 
job. 



GENERATE THE ROOT JOB 

In order to generate the root job, you must do three things: 

• Assemble the configuration file 

• Link the root job and its associated modules 

• Locate the root job 

The Nucleus release diskette contains a SUBMIT file, CROOT.CSD, which you 
can use to perform all three of these functions. In order to use this 
SUBMIT file, you must first prepare your diskettes and place them in the 
proper drives as explained in the "Linking and Locating the Subsystems" 
section of this chapter. Then you can enter the following command: 
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SUBMIT :fx:CROOT( file, date, loc_addr) 

where: 

fx The appropriate disk identifier, indicating the drive 

containing CROOT.CSD. 

file Name of the system configuration file. You should not 

include a disk identifier or an extension with this 
file name. The SUBMIT file assumes that this file 
resides on drive Fl and has the extension "A86". The 
SUBMIT file places the located root job on drive Fl in 
a file of the same name but without the extension and 
the link and locate maps on drive F3 in files of the 
same name but with extensions "MP1" and "MP2" 
respectively. The SUBMIT file also expects file 
CROOT.LIB to be available on drive F2. 

date Date on which this configuration takes place. 

loc_addr Address at which to locate the root job. Examine the 
memory map that you made earlier to determine the 
ending address of the last module that you located. 
Add a padding factor to that value, if necessary, and 
use the sum for the starting address of the root job. 
If you want to specify this value as a hexidecimal 
number, you must include the suffix H. 



NOTE 



If you are providing your own system 
exception handler, you must assemble it 
and modify CROOT.CSD in order to link 
the exception handler in with the root 
job. Its declaration must occur just 
prior to CROOT.LIB in the LINK86 
portion of CROOT.CSD. 



LOAD AND TEST THE SYSTEM 

After you have located all of your jobs (Nucleus, subsystem jobs, 
application jobs, and root job), you are ready to load the system into 
RAM and test it. Use the ICE-86 in-circuit emulator or the iSBC 957A 
package to load your system from disk into RAM. The procedure for using 
ICE-86 is available in the ICE-86 IN-CIRCUIT EMULATOR OPERATING 
INSTRUCTIONS FOR ISIS-II USERS. The procedure for using the iSBC 957 A 
package is described in the iSBC 957A INTELLEC - iSBC 86/12A INTERFACE 
AND EXECUTION PACKAGE USER'S MANUAL. When loading into RAM, be sure to 
load the root job last, so that its starting address gets correctly 
loaded into the code segment (CS) and instruction pointer (IP) registers. 
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When you have loaded your system, test it, correct any errors, reassemble 
or recompile any appropriate program code, re-link and relocate the 
necessary modules, and load the system again with the ICE-86 in-circuit 
emulator or the iSBC 957A package. You can continue this procedure 
(essentially a subset of the procedures described in this chapter) until 
you have created an error-free system. Then you can copy your final 
system to iRMX 86-formatted disks and use the Bootstrap Loader to load 
your system or you can build a final ROM/RAM-based system. 

If you are going to use the Bootstrap Loader, refer to Chapter 11 of this 
manual for configuration information. Also refer to the iRMX 86 LOADER 
REFERENCE MANUAL for information on how to use the Bootstrap Loader. 

If you are going to build a final ROM/RAM-based system, you can, in order 
to shorten the load time, burn your fully tested and completely debugged 
jobs into PROM while still testing and developing other jobs in RAM. 
Then, each time you reload your system, you need only load the jobs you 
are still working on. 

Chapter 5 describes the procedures necessary to configure a ROM/RAM 
system. In general, it describes how to turn a completely debugged RAM 
system into a ROM/RAM system. If you want to burn your jobs into PROM as 
you finish testing and debugging them, make sure that all the fully 
tested and debugged jobs are configured as described in Chapter 5. The 
remaining jobs can be tested in RAM and burned into PROM as they are 
completed. 
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If you have followed the procedures outlined in Chapters 3 and 4 of this 
manual, you should have a fully tested RAM-based iRMX 86 application 
system. In order to create the final ROM/RAM system, you should do the 
following: 

• Minimize the memory address space requirements of your system by 
eliminating the padding factor you used originally when locating 
your jobs. 

• Locate your system so that all the ROM-resident segments are 
contiguous. 

• Test your final system in RAM first, locate it into ROM/RAM, and 
burn the appropriate parts into PROM. 



The remainder of this chapter discusses these procedures in more detail. 
You should read the entire chapter, however, before modifying your 
system. The order in which you perform these procedures depends on your 
individual system requirements. 



MINIMIZING THE MEMORY ADDRESS SPACE 

When you originally located your first-level application jobs, you 
included padding factors in the calculations used to determine starting 
addresses of succeeding jobs. The additional space allocated with the 
padding factors allowed you to make small changes in your programs that 
increased their sizes without changing the LOC86 commands used to locate 
them. The modules, despite increasing in size, did not overlap each 
other. In your final ROM/RAM system, you have already debugged all of 
your programs; their sizes are fixed. So now you can eliminate any extra 
space existing between modules, if you desire. You also estimated the 
size of the root job and included this estimate in the %SAB macro call. 
You can now make a much better estimate of the size of the root job and 
modify your %SAB macro call to indicate this. 

Follow the procedures outlined in the "Locate the Jobs" section of 
Chapter 4 to locate your application first-level jobs again. This time, 
however, leave out the padding factors between jobs. Then modify the 
configuration file by changing the %SAB and %JOB macro calls as follows: 

• Change the %JOB macro call for each application first-level job 
to reflect the new location of the job. 

• Change the %SAB macro calls to reflect the smaller size of 
reserved memory. 
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• Also change the %SAB macro call to more accurately reflect the 

size of the root job. You can make a better estimate of its size 
because you have already located it during the testing phase. 
Use the locate maps generated for it to make a size estimate. 



If the starting address of the root job has changed, specify this new 
address in the CROOT.CSD file. Then, re-submit CROOT.CSD. (The section 
in Chapter 4 entitled "Generating the Root Job" describes this 
procedures. ) 

After you have located your system, load it into RAM and test it again to 
make sure that it functions correctly. 

You can perform this procedure in conjunction with the one described in 
the next section. However, it might be wise to perform them separately 
in order to localize any possible errors. 



LOCATING THE ROM/RAM BASED SYSTEM 

When you located your initial test and development system, as described 
in Chapter 4, you located it by job. That is, if you had three jobs, 
they were laid out as shown in Figure 5-1. 



high memory 



Job 3 MEMORY class 
Job 3 STACK class 
Job 3 DATA class 
Job 3 CODE class 



Job 2 MEMORY class 
Job 2 STACK class 
Job 2 DATA class 
Job 2 CODE class 



Job 1 MEMORY class 
Job 1 STACK class 
Job 1 DATA class 
Job 1 CODE class 



low memory 



Figure 5-1. Memory Layout of a RAM-based System 
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This was relatively easy; it allowed you to use the ORDER control in 
LOC86 and specify only one address for each job with the ADDRESSES 
control. The SUBMIT files used to link and locate each of the subsystems 
used this method also. However, when configuring a ROM/RAM system, you 
should lay out the system by class, not by job. All of the ROM-resident 
segments from all of the jobs should be positioned together. Likewise, 
all of the RAM-resident segments should be positioned together. Thus, if 
you had the same three jobs and were laying out a ROM/RAM system, you 
should structure your memory as shown in Figure 5-2. 



high memory 



Job 3 


CODE class 


Job 2 


CODE class 


Job 1 


CODE class 


Job 3 


MEMORY class 


Job 3 


STACK class 


Job 3 


DATA class 


Job 2 


MEMORY class 


Job 2 


STACK class 


Job 2 


DATA class 


Job 1 


MEMORY class 


Job 1 


STACK class 


Job 1 


DATA class 



ROM 



RAM 



low memory 



Figure 5-2. Memory Layout of a ROM/RAM System 



All of the code classes are located in the upper memory, or ROM, and the 
remainder are located in RAM. 

As you can see, in order to transform your RAM-based system into a 
ROM/RAM system, you must locate your jobs again. Before you do that, 
however, you should prepare a new memory map. 



PREPARE A NEW MEMORY MAP 

To prepare a new memory map, follow the procedures outlined in the 
"Preparing a Memory Map" section of Chapter 4, with one exception. In 
this map record not only the first available RAM address and the last 
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available RAM address, but also the first available ROM address and the 
last available ROM address. You need this information on your memory map 
because for ROM/RAM systems you must specify a location for both the 
ROM-resident code classes and RAM-resident classes. 



LOCATE THE MODULES 

The procedure for locating the modules of a ROM/RAM system, like that for 
a RAM-based system, is an iterative procedure. You locate one module, 
record its addresses in the memory map, and use those values to determine 
where to locate the next module. The format of the LOC86 command used to 
locate these modules is slightly different from the one used to locate 
the RAM-resident system. The format of this command when using a Series 
II development system is as follows: 

LOC86 input_file TO output_file & 

ORDER (CLASSES (DATA, STACK, MEMORY)) & 

SEGSIZE (STACK (stack_size)) & 

ADDRESSES (CLASSES (CODE (rom_address), & 

DATA (ram_address))) & 

MAP PRINT (map_file) & 
OBJECTCONTROLS(NOLINES, NOCOMMENTS, NOPUBLICS, & 
NOSYMBOLS) 



where: 

input file 



Name of the link file produced previously by 
LINK86. 



output file 



Name of the file in which LOC86 writes the 
absolute module. 



stack size 



Size of this job's stack. Use this control 
for those jobs requiring a statically 
allocated stack. If this control is required, 
specify a minimum value of 200H; otherwise 
specify zero. 



rom address 



Absolute starting location of the ROM-resident 
class (code class) of the module. 



ram address 



Absolute starting location of the RAM-resident 
classes of the module. 



map file 



Name of the file in which L0C86 writes the 
locate map. 



If you have a Series III development system, you must also follow the 
additional guidelines listed in the "Using a Series III Development 
System" section of Chapter 4. 
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Use this form of the LOC86 command to locate the Nucleus, each optional 
subsystem first-level job, the root job, and each application first-level 
job. The ORDER and ADDRESSES controls of this command differ from those 
of the RAM-based L0C86 command (refer to the "Locating Application Jobs" 
section of Chapter 4). In this command, the ORDER control does not 
mention the code class. The ADDRESSES control requires that you enter 
two absolute addresses; one to locate the code class in ROM and one to 
locate the remaining classes in RAM. 

The SUBMIT files contained on the subsystem release diskettes that link 
and locate the subsystems and the root job do not use this form of the 
L0C86 command. In order to use these SUBMIT files to create a 
ROM/RAM-based system, you must modify the LOC86 commands contained in 
these files so that they conform to the methods just described. 

One method of locating your ROM/RAM system is as follows: 

1. Locate the Nucleus first. Assign its data class to the lowest 
available RAM address and its code class to the lowest ROM 
address. 

2. Determine the ending addresses of the code class and the memory 
class from the locate map generated by L0C86. Record these 
addresses on the memory map. 

3. Using the next available ROM and RAM addresses as input to LOC86, 
locate the first optional subsystem. 

4. Determine the ending addresses of the code class and the memory 
class from the locate map generated by LOC86. Record these 
addresses on the memory map. Also record the entry point address 
on the memory map. You need to know this address in order to 
specify it in the %JOB macro call. 

5. Go back to step 3 and continue until you have located all of the 
subsystems and all of the application jobs. 



After you have performed this procedure, follow the procedures outlined 
in the "Build the Configuration File" section of Chapter 4 in order to 
modify the configuration file and locate the root job. Note that you 
must modify the CROOT.CSD file in order to locate the root job as 
described in this chapter. You must also reserve all areas of RAM needed 
by the located modules. 



TESTING THE SYSTEM IN RAM 

Before you actually locate a ROM/RAM system, it is recommended that you 
follow the procedures outlined in the previous section, but specify RAM 
addresses for all classes. Then you can load the system into RAM and 
test it before burning code into PROM. After doing this, you can adjust 
the addresses to reflect a ROM/RAM system and build your final system. 
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The Nucleus provides system calls and features to support a wide variety 
of application software activities in a flexible hardware environment. 
Its structure allows you to take advantage of a breadth of support 
without sacrificing memory size or performance. If, after writing the 
code for your application system, you discover that you never make 
certain system calls or never make use of certain Nucleus features, you 
can exclude these system calls and features from the Nucleus of your 
application system. 

The Nucleus also supports a variety of hardware environments. You can 
specify several options for your interrupt controllers and timer. You 
can also include an 8087 Numeric Data Processor in your system. 

The process of including or excluding system calls and features and 
specifying the component environment is called Nucleus configuration. 
Nucleus configuration involves the following operations: 

• Selecting the internal Nucleus features that you want to include 
in your application system and omitting the rest. 

• Selecting the Nucleus system calls that you want to include in 
your application system and discarding the rest. 

• Identifying certain hardware components that make up your system, 
and selecting the attributes of these components. 

You perform these operations by making modifications to two 
Intel-supplied Nucleus configuration files: NTABLE.A86 and NDEVCF.A86. 
NTABLE.A86 defines the system call and feature configuration; NDEVCF.A86 
defines the component configuration. These files are assembly language 
source files which are contained on the Nucleus release diskette. Figure 
6-1 illustrates the structure of these files. After modifying the files, 
you must assemble them and link them with the rest of the Nucleus object 
files and libraries. The following sections describe this configuration 
process in detail. 
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$INCLUDE STATEMENT 
















FEATURE SELECTION 














NUCLEUS CONFIGURATION 
FILE (NTABLE, A86) 








SYSTEM CALL SELECTION 


















END STATEMENT 











$INCLUDE STATEMENT 


















COMPONENT CONFIGURATION 






NUCLEUS CONFIGURATION 
FILE (NDEVCF.A86) 














END STATEMENT 











Figure 6-1. NTABLE. A86 and NDEVCF.A86 Structure 



MODIFYING NTABLE. A86 

As released, NTABLE. A86 defines the full complement of Nucleus system 
calls and internal features. To eliminate system calls or features, you 
must modify this file. 

NTABLE. A86 consists of a series of macro calls. A macro, which 
corresponds in name to a system call or Nucleus internal feature, gives 
directions to the assembler to include the code for that system call or 
feature in the Nucleus. In order to exclude a system call or feature 
from your system, delete the metacharacter of the associated macro call 
(%), and replace it with the comment character (;■)• By doing this, you 
change the macro call into a comment and prevent the assembler from 
evaluating it. 



6-2 



CONFIGURING THE NUCLEUS 



The file NTABLE.MAC, which is available on the Nucleus release diskette, 
contains the definitions of all macros called in NTABLE.A86. NTABLE.A86 
contains an $INCLUDE statement for NTABLE.MAC, which includes it in the 
assembly of NTABLE.A86. 

The following sections describe modifying NTABLE.A86 to select features 
and system calls. 



SELECTING NUCLEUS INTERNAL FEATURES 

If you do not modify NTABLE.A86, the following internal features are 
included with the Nucleus: 

• parameter validation 

• system default exception handler 

You can exclude any or all of these features in order to reduce code size 
and/or increase performance by modifying the feature configuration table 
portion of NTABLE.A86. Figure 6-2 illustrates this table. In order to 
exclude a feature, replace the percent-sign (%) at the beginning of the 
corresponding macro call with a semicolon (;). The following sections 
describe each of these Nucleus internal features. 



$ INCLUDE ( :F2: NTABLE.MAC) 
$EJECi 

; ? ; ; ; ; ; ; ;;;?;; ; ? ; ? ; ; ; ? ; ? ; ? ; ; ; ? ; ; ; ? ; ; ; ; ; ? ; ? ; ; ; ;;:;?;;;;;?;?; ; ; ? ; ? 

NUCLEUS FEATURE CONFIGURATION TABLE 

TO LEAVE QUI A FEATURE, CHANGE THE '%' TO THE COMMENT 
CHARACTER ';' . 

; ; ; ? ; ? ; ; ; ; ; ; ; ; ; ? ; ? ; ? ; ? ; ; ; ? ; ? ; ? ; ; ? ; ; ; ; r ; ; ; ; ; ? ; ? ; ? ; ; ; ? ; ; ; ? ; ? ; ? ; ? ; ? 

%PARAMElER-VALIDATION 
%SYSTEM„EXCEPTIGN«HANDLER 



Figure 6-2. Feature Configuration Table (NTABLE.A86) 



Parameter Validation 

A system call validates input parameters by checking for the existence of 
objects and by verifying that the objects are of the proper types. You 
can exclude all parameter validation by Nucleus system calls from your 
application system by modifying the feature configuration table. To do 
this, replace the percent-sign (%) in the %PARAMETER_VALIDATION macro 
with a semicolon (;). 
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You can include or exclude the support for parameter validation at two 
levels, the system level and the job level. Modifications to NTABLE.A86 
include or exclude the system-level support. You can also include or 
exclude parameter validation on a job-to-job basis with a parameter to 
the CREATE$JOB system call (refer to the iRMX 86 NUCLEUS REFERENCE MANUAL 
for details). If you have included the system-level support, the 
CREATE$JOB system call allows you include or exclude parameter validation 
support on an individual job basis. Table 6-1 shows the relationship 
between system-level and job-level parameter validation support in terms 
of code savings and performance. 



Table 6-1. System-level and Job-level Parameter Validation 



System-level parameter 
validation 


Included 


Excluded 


Job-level parameter 
validation 


Included 


Excluded 


Included 


Excluded 


Is parameter validation 
performed for this job? 


yes 


no 


no 


no 


Does the system 
realize a code savings? 


no 


no 


yes 


yes 


Does the job realize 
a performance 
improvement? 


no 


yes 


yes 


yes 



System Default Exception Handler 

If you do not modify NTABLE.A86, a system default exception handler is 
included in your system automatically. This exception handler deletes 
any task that causes an exceptional condition to occur. However, if you 
remove the %SYSTEM_EXCEPTION_HANDLER macro from NTABLE.A86 by replacing 
the percent-sign (%) with a semicolon (;), an alternate system exception 
handler is included in your system. This alternate handler suspends, 
rather than deletes, a task that causes an exceptional condition. 
Including this alternate system default exception handler could result in 
a significant code savings, if you are not otherwise using the 
DELETE$TASK system call. 



SELECTING NUCLEUS SYSTEM CALLS 

Figure 6-3 shows the system call configuration table portion of 
NTABLE.A86. In order to exclude a system call from your application 
system, replace the percent-sign (%) at the beginning of the 
corresponding macro with a semicolon (;). 
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%ROGFTT)fPe 
%K0DT5ABL£DELETI0N 
%RQ£NaBJ j EDELEIION 
fcRQCATALOGOBJECT 

sroumcaialogobject 
%rglookuporject 

SROCPfcAXFEXTENSlON 
%RQDFL,FTE£XTE<\»SIO.\« 
%RQCPfc:A TECOMPOSITE 
SRQDFLETECOMPGSITE 
%kQlNSPcICTCOMpOSITE 

sroamfrcompo^ixf 

%ROFORC£DEt.ETE 

%KOCR£A.TEJOtf 

%ROOELETEJOB 

%RQUFFSPRING 

%RQCPEATETA6K 

%KODELEXETASK 

%RQSU3PEMDTASK 

%RQRFSUMETASK 

%RQSL£FP 

%KOGETTASKTOKENS 

%ROGETPRIORltY 

*RGSFXPRIOPITY 

%RQCR£ATEMAILbOX 

%RODFuETEMAIt,BOX 

*rqsendmessage 

%rqkfcfivemessagf 

%rocp£atesfmaphore 

%kqoeletesemaphore 

%rosfndunit5 

%KORECEiVEUNlTS 

*kocp£aterfgion 

*rodeleteregton 

%rosfndcontrol 

%roreceivecontrol 

%rqaccfptcontrol 

%R0CREAIE5EGMe:NT 

%rodeletesegment 

%rqgfxsize 

%rggfxpqolattrtb 

%rqsfxpoolmxn 

%rqsft05extensi0n 

fcRQSETINTERRUPT 
%ROENTERINTKRRUPT 
^ROtNABLF 
*kO0I5ABLE 

%rorfsexinterrupt 



Figure 6-3. System Call Configuration Table (NTABLE.A86) 
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%kQGFTLEVEL 

*RO£XITINTFRRUPT 

%RQSTGNALINT€HRUPT 

%RQWAXT1NTFHRUPT 

%RQGFTFXCEPTlONHANDLFR 

%RQSFTEXCEPTTONhANDLEH 

%ROSTGNALEXCEPTlON 



END 



Figure 6-3. System Call Configuration Table (NTABLE.A86) (continued) 



MODIFYING NDEVCF,A86 

NDEVCF.A86 consists of a series of macro calls that specify information 
about the following components: 

• Programmable Interrupt Controller (PIC) 

• Programmable Interval Timer (PIT) 

• 8087 Numeric Data Processor (NDP) 

As released, NDEVCF.A86 describes a standard system consisting of a 
master 8259A PIC and an 8253 PIT. If your system varies from this 
configuration, or if you want to change the attributes of any of the 
components, you must modify NDEVCF.A86. Figure 6-4 illustrates the 
component configuration portion of NDEVCF.A86. 



$iNcr.UDE(:F2:NDEVCF. M AC) 

%MASTER-PlC(R25yA,0C0H,0,0) 

;SLAVE,,PIC( SLAVF-TYP;e/ BASt.P0HT r 'fcDGE.VS-LEVFLr MA5TFR.L.FVF 
%TTMFR(8 2b3,ODOH,2 8H,l22F8) 
r'NDP^SUPPGRTC FMCODED-LEVEL ) 
END 

Figure 6-4. Component Configuration Table (NDEVCF.A86) 
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The file NDEVCF.MAC, which is available on the Nucleus release diskette, 
contains the definitions of all macros called in NDEVCF.A86. NDEVCF.A86 
contains an $INCLUDE statement which includes NDEVCF.MAC in the assembly 
of NDEVCF.A86. 

The following sections describe modifying NDEVCF.A86 to include 
information about individual components. 



PROGRAMMABLE INTERRUPT CONTROLLER (PIC) CONFIGURATION 

The iRMX 86 Operating System supports a hardware environment with either 

a single PIC (non-cascaded mode) or several PICs (cascaded mode). Two 

macros are available to define the environment and the attributes of each 
PIC. These macros are: 

%MASTER_PIC 
%SLAVE_PIC 

The %MASTER_PIC macro defines the attributes of the master PIC. This 
macro is required for both cascaded and non-cascaded mode. The 
%SLAVE_PIC macro is required only in cascade mode and defines the 
attributes of a slave PIC. One %SLAVE_PIC macro is required for each 
slave PIC in the system. All %SLAVE_PIC macros must follow the 
%MASTER_PIC macro in NDEVCF.A86. The following sections describe the 
formats of the two macros. 



%MASTER_PIC Macro 

The %MASTER_PIC macro defines the attributes of the single PIC, when in a 
non-cascaded environment, or the master PIC, when in a cascaded 
environment. The format of this macro call is as follows: 

%MASTER_PIC(8259A, base_port, 0, 0) 

Where: 

base_port 

Port address of the master PIC. When using Intel processor boards 
such as the iSBC 86/12A and iSBC 86/05, you must specify a value of 
0C0H for this parameter. The Nucleus assumes that all ports are at 
even port addresses (base port + 0, base port + 2, base port + 4, and 
so on). 

Because the Operating System currently supports only the 8259A PIC, you 
must specify the remaining parameters as shown. These remaining 
parameters are reserved for future support upgrades. For further 
information about the 8259A PIC, refer to THE 8086 FAMILY USER'S MANUAL. 

As released, NDEVCF.A86 contains a default %MASTER_PIC call that defines 
an 8259A PIC with a port address of 0C0H. If your master PIC requires a 
different value, you must modify this call. 
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%SLAVE_PIC Macro 

The %SLAVE_PIC macro defines the attributes of a slave PIC in a cascaded 
environment. You must include one %SLAVE_PIC macro for each slave PIC in 
your system. All of these %SLAVE_PIC calls must follow the %MASTER_PIC 
call. The format of the %SLAVE_PIC call is as follows: 

%SLAVE_PIC(8259A, base_port, edge_vs_level, master_level) 

Where : 

base_port Port address of the slave PIC. The Nucleus assumes 

that all ports are at even port addresses (base port + 
0, base port + 2, base port + 4, and so on). 

edge_vs_level Triggering mode for the PIC. Specify this parameter 
as follows: 

value description 

Edge triggering mode 

nonzero Level triggering mode 

master_level Interrupt level on the master PIC which connects 

to the slave PIC. You must specify a value in 
the range through 7 for this parameter. 

Because the Operating System currently supports only the 8259A PIC, you 
must specify the remaining parameter as shown. This remaining parameter 
is reserved for future support upgrades. 

As released, NDEVCF.A86 does not include a %SLAVE_PIC call. If your 
system includes multiple interrupt controllers in a cascaded environment, 
you must modify NDEVCF.A86 to include a %SLAVE_PIC call for each slave 
PIC. 



PROGRAMMABLE INTERVAL TIMER (PIT) CONFIGURATION 

You can specify the attributes of the PIT by calling the %TIMER macro. 
The format of this macro call is as follows: 

%TIMER(8253, base_port, level, count) 

Where: 

base_port Port address of the PIT. When using Intel processor 
boards such as the iSBC 86/12A and iSBC 86/05, you 
must specify a value of 0D0H for this parameter. The 
Nucleus assumes that all ports are at even port 
addresses (base port + 0, base port +2, base port + 
4, and so on). 
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level Encoded value specifying the interrupt level of the 
master PIC to which this timer is connected. This 
value corresponds to the interrupt levels as follows 

value level 



x8H Master levels MO through M7 

(0 > x > 7) 

count Down count value that is loaded into the timer 

register. You should use the following formula to 
determine this value: 

count = # tick X clock_frequency 

where : 

tick The period of time, in milliseconds, 
that you wish to specify as a clock 
interval. 

clock_ The frequency, in kilohertz, of the 
frequency clock input to the timer. 

Because the Operating System currently supports only the 8253 PIT, the 
remaining parameter must be specified as shown. This remaining parameter 
is reserved for future support upgrades. For further information 
concerning the 8253 PIT, refer to THE 8086 FAMILY USER'S MANUAL. 

As released, NDEVCF.A86 contains a default %TIMER call which specifies a 
port address of 0D0H, an interrupt level of 2, and a 1.288 megahertz 
clock with 10 millisecond clock interval. If your system requires a 
different specification, you must modify NDEVCF.A86. 



8087 NDP CONFIGURATION 

If your system contains an 8087 NDP, you must call the %NDP_SUPPORT 
macro. This macro sets up a system interrupt handler for the NDP and 
associates it with a specified Programmable Interrupt Controller. The 
format of the macro call is as follows: 

%NDP_SUPPORT ( level ) 

where : 

level Encoded value specifying the interrupt level connected 
to the 8087 NDP interrupt pin. This value corresponds 
to the interrupt level as follows: 
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value level 



x8H Master interrupt levels MO through 

(0 > x > 7) M7. 

yzH Slave interrupt levels 00 through 

(0>y>7) 77. 
(0 > z > .7) 

No other application code can make use of this 
interrupt level. Also, any task which uses the 8087 
NDP must not have a priority high enough to mask this 
interrupt level. Refer to the iRMX 86 NUCLEUS 
REFERENCE MANUAL for information concerning interrupt 
levels and priorities. 

As released, NDEVCF.A86 does not include the %NDP_SUPPORT macro call. If 
your system contains an 8087 NDP, you must modify NDEVCF.A86 to include 
the %NDP_SUPP0RT call. 

For further information about the 8087 NDP, refer to THE 8086 FAMILY 
USER'S MANUAL, NUMERICS SUPPLEMENT. 



MAXIMAL, DEFAULT, AND MINIMAL CONFIGURATION 

The maximal Nucleus configuration (for features and system calls) 
consists of all supported Nucleus system calls, parameter validation, and 
the system default exception handler. This maximal configuration is the 
same as the default configuration. You do not need to modify NTABLE.A86 
in order to obtain this maximal configuration. 

The default component configuration defines the attributes of the 
components as they exist on the iSBC 86/12A single board computer. 

The minimal Nucleus configuration for a Nucleus-only application system 
consists of no configurable internal features and only the following 
system calls: 

CREATE $ JOB 
SUSPEND$TASK 
RESUME $TASK 
GET$TASK$TOKENS 
SIGNAL$EXCEPTION 

You must always include these system calls in your application system. 
You can, of course, include any or all other system calls and internal 
features that your application system requires. 
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ASSEMBLING THE CONFIGURATION FILES, LINKING AND LOCATING THE NUCLEUS 

After you have made any necessary modifications to the Nucleus 
configuration files, NTABLE.A86 and NDEVCF.A86, you must assemble them 
and link and locate the Nucleus. NUCLUS.CSD, a SUBMIT file contained on 
the Nucleus release diskette, can be used to perform these functions. In 
order to use this SUBMIT file, you must first prepare your diskettes and 
place them in the proper drives of your development system as explained 
in the "Linking and Locating the Subsystems" section of Chapter 4. You 
should also examine NTABLE.A86 and NDEVCF.A86 to make sure that the 
$INCLUDE statements contain the proper disk identifiers. Then you can 
enter the following command: 

SUBMIT :fx:NUCLUS(date, loc adr) 



where : 

fx The appropriate disk identifier, indicating the drive 

containing NUCLUS.CSD. 

date The date on which you submit the file (maximum of nine 

characters) • 

loc_adr The address at which to locate the Nucleus. If you 

want to enter this value as a hexidecimal number, you 
must include the suffix H. 

This command assembles NTABLE.A86 and NDEVCF.A86, links them together 
with other libraries that contain the Nucleus code and locates the 
Nucleus at the specified address. It places the located Nucleus in file 
NUCLUS on drive Fl. It also places the assembly listing, link map, and 
locate map on drive F3 in files NTABLE.LST, NUCLUS. MP1, and NUCLUS. MP2, 
respectively. 



NOTE 



The link map for the Nucleus always 
contains a warning message indicating a 
possible overlap. This is a normal 
message for the Nucleus. It does not 
indicate an error in the LINK86 command. 



NUCLEUS INITIALIZATION ERRORS 

If the Nucleus encounters an error during the initialization process, it 
places diagnostic information in the processor registers and halts the 
processor. Errors can occur during two operations: 

Nucleus and memory initialization 

Job creation by the root task 
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The value placed in the AX register determines which type of error 
occurred. The following sections outline these errors. 



NUCLEUS AND MEMORY INITIALIZATION ERRORS 

If an error occurs during the Nucleus and memory initialization process, 
the Nucleus sets the processor registers as follows: 



register 
AX 

BX 



value 
11H 

0D001H 

0D002H 

0D003H 
0D004H 

0D005H 
0D006H 

0D007H 



description 

A Nucleus or memory initialization 
error occured. The BX register 
contains a description of the error. 

There are no SABs defined. There must 
be at least one. 

The interrupt vector is not contained 
in a SAB. 

Reserved. 

There is not enough contiguous RAM 
available for the root job's memory 
pool. 

The SABs are out of order or overlap. 

There is not enough RAM available for 
the system resources of the Nucleus. 

An invalid minimum transfer size was 
specified in the %SYSTEM macro. Refer 
to the "%SYSTEM Macro" section of 
Chapter 4 for a description of the 
minimum transfer size. 



ROOT TASK ERRORS 

If the root task encounters an error while it is creating the first-level 
jobs of your application system, it sets the processor registers as 
follows: 



register 
AX 



value 



21H 



description 

A root task error occurred. The BX, 
CX, and DL registers contain a 
description of the error. 
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register 
BX 



value 



varies 



CX 



varies 



DL 



varies 



description 

BX is set as an index to indicate which 
%JOB call in the system configuration 
file caused the error. For example, 1 
implies the first %JOB call in the 
file, 2 the second, and so forth. 

CX contains the exception code returned 
from the CREATE$JOB system call that 
was called to create the first-level 
job. 

DL contains the number of the parameter 
in the %JOB call that caused the 
error. If DL is greater than 8, the 
parameter number is DL +1. Otherwise, 
the parameter number is DL. 
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The Terminal Handler provides real-time, asynchronous I/O between an 
operator terminal and tasks running under the iRMX 86 Operating System. 
Terminal Handler configuration involves selecting characteristics of the 
Terminal Handler and specifying information about the processor board and 
the terminal. You perform these operations by making modifications to an 
Intel-supplied Terminal Handler configuration file. This file, 
MCONFG.A86, is an assembly language source file which is contained on the 
Terminal Handler release diskette. 

As released, MC0NFG.A86 defines a Terminal Handler that communicates with 
a 9600 baud terminal and runs on an iSBC 86/12A single board computer. 
If you want the Terminal Handler to run on a different hardware 
configuration, or if you want to change some of the characteristics of 
the Terminal Handler, you must modify MCONFG.A86, assemble it, link it 
with the rest of the Terminal Handler object files and libraries, and 
locate the Terminal Handler at an absolute address. The following 
sections discuss this configuration process in detail. 



MODIFYING MC0NFG.A86 

MCONFG.A86 can consist of a series of macro calls which identify the 
characteristics of the Terminal Handler, the terminal, and the processor 
board. Figure 7-1 illustrates the released MC0NFG.A86. As you can see 
by this figure, the released file contains only an $INCLUDE statement. 
This $INCLUDE statement causes the Terminal Handler to be assembled with 
the default configuration parameters. To change the configuration, you 
must add macro calls to MC0NFG.A86. MCONFG.A86 can contain calls to the 
following macros: 

%TH_1 9200_BAUD_COUNT 

%MTH 

%TH_INT_LEVELS 

%TH_USART 

%TH_TIMER 

%TH_CHAR_LENGTH 

%TH_MAILBOX_NAMES 

The file MTHCNF.MAC, which is available on the Terminal Handler release 
diskette, contains the definitions of all these macros. MCONFG.A86 
contains an $INCLUDE statement for MTHCNF.MAC, which includes it in the 
assembly of MCONFG.A86. 

The following sections describe the macro calls in detail. 



7-1 



CONFIGURING THE TERMINAL HANDLER 



Sinclude(:£2:mtncnf.mac) 
end 



Figure 7-1. Terminal Handler Configuration File (MCONFG.A86) 



%TH_19200_BAUD_COUNT MACRO 

If your system's programmable interval timer (PIT) has a clock input 
frequency other than 1.2288 megahertz, you must call this macro to set 
the limits on the baud rate attributes of the Terminal Handler. The 
format of the call to this macro is as follows: 

%TH_1 9 200_BAUD_COUNT ( count ) 

where : 

count Value that when loaded into the timer register 

generates a maximum baud rate of 19200. The value 
that you enter for this parameter depends on the clock 
input frequency to your system's PIT (refer to the 
following paragraphs). If you do not include the 
macro call, a default value of 4 is assumed, which 
corresponds to the default frequency of the clock 
input to the 8253 PIT on the iSBC 86/12A board. 

To derive the value to use for the count parameter, you must first 
determine the clock input frequency to the PIT (in hertz). Then 
substitute this frequency into the following equation: 

(1) result = (clock frequency in hertz) / (19200 X 16) 

Then substitute "result" from equation 1 into the following equation: 

(2) fraction = result - INT(result) 

where INT(result) is an integer obtained by truncating the fractional 
portion of "result". If "fraction" from equation 2 is greater than or 
equal to 0.5, then: 

(3) count = INT (result) + 1 

error fraction = 1.0 - fraction 
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If "fraction" is less than 0.5, then: 

(4) count = INT(result) 

error_f raction = fraction 

Before placing "count" from equation 3 or 4 into the %TH__19200_BAUD_COUNT 
call, you should first determine the percentage of error in this value. 
You do this by solving the following equation: 

(5) % error = (error_f raction / count) X 100 

If the percentage of error is less than 3%, you can use any Terminal 
Handler-supported baud rate (which you later specify in the %MTH macro, 
described later in this chapter). However, if the percentage of error is 
3% or greater, you will have to perform the following additional 
computations. 

First, determine the desired baud rate of the terminal. Substitute this 
value for the 19200 in equation 1 and recompute the value of "count" 
(equations 1 through 4). Again determine the percentage of error 
(equation 5). If the error is less than 3% with the new baud rate, you 
can use the Terminal Handler with that new baud rate (and specify it in 
the %MTH macro). However, if the percentage of error is still 3% or 
greater, the combination of desired baud rate and clock frequency is 
unacceptable to the Terminal Handler. You will have to change one or the 
other. After doing this, recompute the error to verify that it falls 
below the 3% level. 

Regardless of the baud rate you eventually choose, use the "count" value 
as originally computated (with the 19200 value) as input to the 
%TH_19200_BAUD_COUNT macro call. 

If MC0NFG.A86 does not contain a call to the %TH_19200_BAUD_COUNT macro, 
the Terminal Handler will operate as if you had specified this macro call 
with a value of 4 for the count parameter. This is an appropriate value 
for the default input frequency to the 8253 PIT on the iSBC 86/12A board 
(or any timer with an input frequency of 1.2288 megahertz). 

If you specify this macro call, you must place it as the first macro call 
in MC0NFG.A86. 



%MTH MACRO 

This macro allows you to designate the baud rate and rubout 
charateristics of your terminal. The format of this macro is as follows: 

%MTH (baud_rate, rubout_mode, blank_char) 
where : 



7-3 



CONFIGURING THE TERMINAL HANDLER 



baud_rate Baud rate of the terminal being used with the Terminal 
Handler. Specify one of the following rates: 

19200 
9600 
4800 
2400 
1200 

600 

300 

150 

110 

Refer to the "%TH_19200_BAUD_COUNT Macro" section of 
this chapter to ensure that the value you enter for 
this parameter will cause the Terminal Handler to 
operate correctly. If you omit the macro call, a 
default value of 9600 is assumed. 

rubout__mode Terminal Handler rubout mode. Enter one of the 
following: 

1 The Terminal Handler echoes the deleted 
character back to the terminal. 

2 The Terminal Handler replaces the deleted 
character with the blank character. 

If you omit the macro call, a default value of 2 is 
assumed. 

blank_char Blanking character for use with option 2 of 

rubout_mode. If you omit the macro call, the default 
blanking character is assumed to be the ASCII space 
(020H). 

If MC0NFG.A86 does not contain the %MTH call, the Terminal Handler 
assumes a 9600 baud terminal with blanking mode 2 and a blanking 
character of ASCII space (020H). 



%TH_USART MACRO 

This macro allows you to designate the port address of the USART. The 
format of this macro call is as follows: 

%TH_USART ( base_por t ) 

where: 



base_port Hexadecimal number specifying the base port address of 
the USART. The Terminal Handler assumes that all 
ports are at even port addresses (base port + 0, base 
port + 2, base port + 4, and so on). If you omit the 
macro call, a value of 0D8H is assumed. 
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If MCONFG.A86 does not include a call to %TH_USART, the Terminal Handler 
assumes a USART port address of 0D8H. This value must be used for Intel 
processor boards, such as the iSBC 86/12A and iSBC 86/05 single board 
computers. 



%TH_TIMER MACRO 

This macro allows you to specify information about the programmable 
interval timer (PIT). The format of the macro call is as follows: 

%TH_TIMER(base_port, baud_counter ) 

where : 

base_port Port address of the PIT. The Terminal Handler assumes 
that all ports are at even port addresses (base port + 
0, base port + 2, base port + 4, and so on). If you 
omit the macro call, a value of 0D0H is assumed. 

baud_counter Number of the PIT counter connected to the USART clock 
input. The output of this counter generates the 
Terminal Handler baud rate. You must specify a value 
from to 2 for this parameter. If you omit the macro 
call, a value of 2 is assumed. You must ensure that 
the counter you select is not used by the Nucleus or 
any other module. The Nucleus uses counters and 1 
of the timer to which it is connected. Therefore, if 
your system does not contain an off -board timer, you 
must use counter 2 for the Terminal Handler. 

If MCONFG.A86 does not contain the %TH_TIMER macro call, the Terminal 
Handler operates as if you had specified this macro call with a value of 
0D0H for the base_port parameter and a value of 2 for the baud_counter 
parameter. These values must be used for Intel processor boards, such as 
the iSBC 86/12A and iSBC 86/05 single board computers. 



%TH_CHAR_LENGTH MACRO 

This macro allows you to specify the number of bits of valid data per 
character sent from the USART. The format of this macro call is as 
follows: 

%TH_CHAR_LENGTH( length) 

where : 

length Number of bits of valid data per character sent from 
the USART. The only acceptable values for this 
parameter are 7 and 8. If you omit the macro call, a 
value of 7 is assumed. 
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If MCONFG.A86 does not contain the %TH_CHAR_LENGTH macro, the Terminal 
Handler assumes 7 bit characters, which is appropriate for systems using 
the ASCII character set. 



%TH_MAILBOX_NAMES MACRO 

This macro allows you to specify names for the Terminal Handler's input 
and output mailboxes. The format for this macro call is as follows: 

%TH_MAILBOX_NAMES(input_mailbox, output_mailbox) 

where: 

input_mailbox Name of the mailbox used for input to the Terminal 
Handler. Legitimate names consist of 12 or less 
alphanumeric characters. If you omit the macro call, 
the name RQTHNORMIN is assumed. 

output_mailbox Name of the mailbox used for output by the Terminal 
Handler. Legitimate names consist of 12 or less 
alphanumeric characters. If you omit the macro call, 
the name RQTHNORMOUT is assumed. 

If MCONFG.A86 does not contain the %TH_MAILBOX_NAMES macro call, the 
Terminal Handler uses the names RQTHNORMIN and RQTHNORMOUT for its input 
and output mailboxes. 

If you intend to use the Basic I/O System's On Board USART driver to 
communicate with the Terminal Handler, you must provide a Terminal 
Handler whose input and output mailboxes have the names RQTHNORMIN and 
RQTHNORMOUT, respectively. The Basic I/O System will communicate only 
with a Terminal Handler that uses these mailbox names. 



%TH_INT_LEVELS MACRO 

This macro allows you to specify the interrupt levels used by the 
Terminal Handler for input and output. The format of the call to this 
macro is as follows: 

%TH_INT_LEVELS(input_level, output_level) 

where: 

input_level Encoded value specifying the interrupt level used for 
input to the Terminal Handler. This value corresponds 
to the interrupt level as follows: 

value level 

x8H Master interrupt levels MO through 

(0 > x > 7) M7. 
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value level 



yzH Slave interrupt levels 00 through 

(0>y>7) 77. 
(0 > z > 7) 

If you omit the macro call, a value of 68H is assumed. 

output__level Encoded value specifying the interrupt level used for 
output by the Terminal Handler. This value 
corresponds to the interrupt level as follows: 

value level 

x8H Master interrupt levels MO through 

(0>x>7) M7. 

yzH Slave interrupt levels 00 through 

(0>y>7) 77. 
(0 > z > 7) 

If you omit the macro call, a value of 78H is assumed. 

The input interrupt level must be a higher priority level than the output 
interrupt level. The iRMX 86 NUCLEUS REFERENCE MANUAL describes the 
relationship between interrupt levels and priorities. 

The maximum priority of user tasks in an application system containing 
the Terminal Handler depends on the interrupt levels assigned to the 
Terminal Handler with the %TH_INT_LEVELS macro. The priorities of all 
user tasks must be lower (numerically higher) than the lowest priority 
interrupt task in the Terminal Handler. In the default configuration, 
the Terminal Handler's output interrupt level is set to M7, which 
corresponds to a priority of 130 for the output interrupt task. Thus, 
with the default Terminal Handler configuration, all user tasks must have 
a priority lower (numerically higher) than 130. 

If MCONFG.A86 does not contain the %TH_INT_LEVELS macro call, the 
Terminal Handler assumes master level M6 (68H) for input and master level 
M7 (78H) for output. 



ASSEMBLING MC0NFG.A86, LINKING AND LOCATING THE TERMINAL HANDLER 

MTH.CSD, a SUBMIT file contained on the Terminal Handler release 
diskette, can be used to assemble MCONFG.A86 and link and locate the 
Terminal Handler. In order to use this SUBMIT file, you must first 
prepare your diskettes and place them in the proper drives of your 
development system as explained in the "Linking and Locating the 
Subsystems" section of Chapter 4. You may also have to make 
modifications to MTH.CSD before submitting it, depending on your Terminal 
Handler requirements. This section describes MTH.CSD modifications and 
the format of the command to submit this file. 
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MTH.CSD MODIFICATIONS 

If you are providing code to implement control-C semantics, you must 
place this code in a procedure named RQABORTAP, which uses only near 
calls. Since this procedure runs as part of the interrupt task for the 
Terminal Handler, which does not have an exception handler, it should not 
make any system calls to delete its task, delete its job, suspend its 
task, or change its priority. The environmental condition codes 
generated as a result of making these system calls are returned in-line. 
Assemble this procedure and modify MTH.CSD to place its object file name 
in the LINK86 input list immediately after MCONFG.OBJ. Refer to the iRMX 
86 TERMINAL HANDLER REFERENCE MANUAL for further information on the 
default control-C semantics. 

The Human Interface release diskette includes a library HI. LIB which 
contains a module HCONTC that implements control-C semantics for the 
Human Interface. If you are planning to include the Human Interface in 
your application system and wish include the control-C features of the 
Human Interface, you must link this module in with the Terminal Handler 
through which the Human Interface communicates. Include the following 
line in the LINK86 input list immediately after MCONFG.OBJ: 

:fx:HI.LIB (HCONTC), & 

This module should replace any control-C semantics files that you would 
otherwise include. 



SUBMITTING MTH.CSD 

Enter the following command to assemble MCONFG.A86 and link and locate 
the Terminal Handler: 



SUBMIT :fx:MTH(date, loc adr, type) 



where : 



fx The appropriate disk identifier, indicating the drive 

containing MTH.CSD. 

date The date on which you submit the file (maximum of nine 

characters). 

loc_adr The address at which to locate the Terminal Handler. 
If you want to enter this value as a hexadecimal 
number, you must include the suffix H. The base 
portion of this value is the base portion of the 
Terminal Handler^ entry point. The offset portion of 
the entry point is 0. You must specify this entry 
point in the %J0B macro call for the Terminal Handler. 
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type Type of Terminal Handler you wish to create. Enter 

one of the following: 

RQOUTPUT An output-only version of the 
Terminal Handler is generated. 

RQINPUT An input and output version of the 
Terminal Handler is generated. 



This command assembles MCONFG.A86, links it together with other modules 
that contain Terminal Handler code, and locates the Teminal Handler at 
the specified address. It places the located Terminal Handler in file 
MTH on drive Fl. It also places link and locate maps on drive F3 in 
files MTH.MP1 and MTH.MP2 respectively. 

You must specify a %JOB macro in the system configuration file for the 
Terminal Handler (refer to Chapter 4). In this macro, the entry point 
depends on the address at which you locate the Terminal Handler (CS:0). 
The data segment base should be specified as (the Terminal Handler 
assigns its own data segment). 



CREATING MULTIPLE VERSIONS OF THE TERMINAL HANDLER 

If desired, your iRMX 86 system can contain multiple versions of the 
Terminal Handler. This may be desirable if, for example, you have two 
tasks that use the Terminal Handler and you want to communicate with 
these tasks from separate terminals. In order to create multiple 
versions of the Terminal Handler, you must obey the following rules: 

• Each Terminal Handler must use different input and output mailbox 
names. That is, the %TH_MAILBOX_NAMES calls must be different. 

• Each Terminal Handler must use a unique USART. This also means 
that the %TH_USART calls must be different. 

• Each Terminal Handler must use a unique timer. This also means 
that the %TH_TIMER calls must be different. 

, • Each Terminal Handler must use different interrupt levels. This 
also means that the %TH_INT_LEVELS calls must be different. 

• The code for the Terminal Handlers must be located in different, 
non-overlapping areas; each Terminal Handler must have its own 
data area. 

• Each Terminal Handler must have its own %JOB macro in the system 
configuration file. 

If you adhere to these rules, you can create multiple versions of the 
Terminal Handler in your application system. 
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Because the Debugger contains a copy of the Terminal Handler, Debugger 
configuration is almost identical to Terminal Handler configuration 
(except that only one Debugger can be present in the application 
system). Debugger configuration involves selecting characteristics of 
the Debugger's Terminal Handler and specifying information about the 
processor board and the terminal. You perform these operations by making 
modifications to an Intel-supplied Debugger configuration file. This 
file, DTHCNF.A86, is an assembly language source file which is contained 
on the Debugger release diskette. 

As released, DTHCNF.A86 defines a Terminal Handler for the Debugger that 
communicates with a 9600 baud terminal and runs on a system that uses an 
iSBC 86/12A single board computer. If you want the Debugger's Terminal 
Handler to run on a different hardware configuration, or if you want to 
change some of the characteristics of that Terminal Handler, you must 
modify DTHCNF.A86, assemble it, link it with the rest of the Debugger 
object files and libraries, and locate the Debugger at an absolute 
address. The following sections discuss this configuration process in 
detail. 



MODIFYING DTHCNF.A86 

DTHCNF.A86 can consist of a series of macro calls which identify the 
characteristics of the Debugger's Terminal Handler, the terminal, and the 
processor board. Figure 8-1 illustrates the released DTHCNF.A86, which 
causes the Debugger to be assembled with default configuration 
parameters. To modify this file, refer to the "Modifying MCONFG.A86" 
section of Chapter 7. The macro calls that you can place in DTHCNF.A86 
are exactly the same as those described in Chapter 7. 



$include(:fl;dtncnf.nr>ac) 
end 



Figure 8-1. Debugger Configuration File (DTHCNF.A86) 
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ASSEMBLING DTHCNF.A86, LINKING AND LOCATING THE DEBUGGER 

DB.CSD, a SUBMIT file contained on the Debugger release diskette, can be 
used to assemble DTHCNF.A86 and link and locate the Debugger. In order 
to use this SUBMIT file, you must first prepare your diskettes and place 
them in the proper drives of your development system, as explained in the 
"Linking and Locating the Subsystems" section of Chapter 4. You may also 
have to make modifications to DB.CSD before submitting it, depending on 
your Debugger requirements. This section discusses DB.CSD modifications 
and the format of the command to submit this file. 



DB.CSD MODIFICATIONS 

If you are providing code to implement control-C semantics, you must 
place this code in a procedure named RQABORTAP, which uses only near 
calls. Since this procedure runs as part of the interrupt task for the 
Terminal Handler, which does not have an exception handler, it should not 
make any system calls to delete its task, delete its job, suspend its 
task, or change its priority. The environmental condition codes 
generated as a result of making these system calls are returned in-line. 
Assemble this procedure and modify DB.CSD to place its object file name 
in the LINK86 input list immediately after DTHCNF.OBJ. Refer to the iRMX 
86 TERMINAL HANDLER REFERENCE MANUAL for further information on the 
default control-C semantics. 

The Human Interface release diskette includes a library HI. LIB which 
contains a module HCONTC that implements control-C semantics for the 
Human Interface. If you are planning to include the Human Interface in 
your application system and wish include the control-C features of the 
Human Interface, you must link this module in with the Terminal Handler 
with which the Human Interface communicates. If the Human Interface 
communicates with the Debugger's Terminal Handler, you must link this 
module in with the Debugger. To do this, include the following line in 
the LINK86 input list immediately after MCONFG.OBJ: 

:fx:HI.LIB (HCONTC), & 

This module should replace any control-C semantics files that you would 
otherwise include. 



SUBMITTING DB.CSD 

Enter the following command to link and locate the Debugger: 

SUBMIT :fx:DB(date, loc_adr) 

where: 

fx The appropriate disk identifier, indicating the 

drive containing DB.CSD. 
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date The date on which you submit the file (maximum 

of nine characters). 

loc_adr The address at which to locate the Debugger. If 

you want to enter this value as a hexadecimal 
number, you must include the suffix H. The base 
portion of this value is the base portion of the 
Debugger's entry point. The offset portion of 
the entry point is 0. You must specify the 
entry point in the %J0B macro call for the 
Debugger. 

This command links together the modules that make up the Debugger and 
locates the Debugger at the specified address. It places the located 
Debugger in file DB on drive Fl. It also places the link and locate maps 
on drive F3 in files DB.MP1 and DB.MP2 respectively. 

You must specify a %J0B macro in the system configuration file for the 
Debugger (refer to Chapter 4). In this macro, the entry point depends on 
the address at which you locate the Debugger (CS:0). The data segment 
base should be specified as (the Debugger assigns its own data segment). 
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Basic I/O System configuration involves the following two operations: 

• Selecting the features and system calls of the Basic I/O System 
that you want to include in your application system and 
discarding those that you do not want. 

• Supplying the Basic I/O System with information about the I/O 
devices on your system. 



You perform both of these operations by making modifications to two 
Intel-supplied Basic I/O System configuration file: ITABLE.A86 and 
IDEVCF.A86. These files, which are contained on the Basic I/O System 
release diskette, are assembly language source files. They contain the 
following information: 

ITABLE.A86 This file contains information about the interfaces 
available with the Basic I/O System, the individual 
system calls associated with each interface, and the 
internal features of the Basic I/O System. As 
released, ITABLE.A86 defines the full complement of 
system calls and internal features. 

IDEVCF.A86 This file contains a description of the devices 

supported, along with device and unit information for 
each supported device. As released, IDEVCF.A86 
describes a number of commonly available devices. 

Figure 9-1 illustrates the structure of these two files. 
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NON-FILE/CONNECTION 
INTERFACE 



FILE/CONNECTION 
INTERFACE 



SINCLUDE STATEMENTS 
















SYSTEM CALL SELECTION 
















FILE DRIVER GLOBAL DATA 










I/O SYSTEM 
CONFIGURATION 
FILE (ITABLE.A86) 


FILE DRIVER TABLES 
















OPTIONAL FEATURE SELECTION 
















END STATEMENT 











DESCRIBING 
I/O DEVICES 



SINCLUDE STATEMENTS 














i 


DEVICE-UNIT INFORMATION 
BLOCKS 






DEVICE INFORMATION 
TABLES 








I/O SYSTEM 
CONFIGURATION 
FILE (IDEVCF.A86) 


UNIT INFORMATION 
TABLES 










GENERAL DEVICE INFORMATION 










END STATEMENT 











Figure 9-1. ITABLE.A86 and IDEVCF.A86 Structure 
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The following sections of this chapter show how to modify ITABLE.A86 and 
IDEVCF.A86 in order to produce a Basic I/O System that supports your 
individual needs. They also show how to assemble this file and link and 
locate the Basic I/O System. Some of the sections in this chapter list 
selected portions of the configuration file in order to aid you in the 
configuration process. 



INCLUDE FILES 

ITABLE.A86 must contain an $INCLUDE statement for the following file as 
the first statement (other than comments or general controls such as 
$TITLE) in the configuration file. 

ITABLE.INC This file contains segment, structure, macro, and 

miscellaneous definitions for the non-file /connection 
interfaces, the file/connection interface, file driver 
global data, and internal feature configuration. 

IDEVCF.A86 must contain an $INCLUDE statement for the following file as 
the first statement (other than comments or general controls such as 
$TITLE) in the configuration file. 

IDEVCF.INC This file contains segment, structure, and macro 

definitions for device driver configuration; structure 
definitions for device configuration; and the 
defination of the %DEVICE_TABLES macro. This macro is 
described in the "General Device Information" section 
of this chapter. 



These files are contained on the Basic I/O System release diskette. As 
released, ITABLE.A86 and IDEVCF.A86 contain $INCLUDE statements for these 
files. However, you should examine ITABLE.A86 and IDEVCF.A86 to ensure 
that the $INCLUDE statements contain the correct disk identifiers. 



SELECTING NON-FILE /CONNECTION INTERFACE FEATURES (ITABLE.A86) 

The non-file/connection interfaces consist of the following: 

parameter interface This interface supplies local parameters 

which the Basic I/O System uses each time 
a task makes a Basic I/O System call. 

configuration interface This interface is used by Operating System 

extensions to dynamically configure the 
Basic I/O System. 

power-fail interface This interface informs the Basic I/O 

System of impending power failure or power 
available conditions. 
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date/time interface This interface supplies date and time 

information. 



In ITABLE.A86, each non-file/ connect ion interface consists of a group of 
related system calls. Figure 9-2 contains the portion of ITABLE.A86 that 
defines the non-file/connection interfaces. This code consists of macro 
calls which correspond in name to system calls. Each macro gives 
directions to the assembler to include the code for the corresponding 
system call in the Basic I/O System. 

If you do not modify this portion of ITABLE.A86, all of the system calls 
associated with the non-file /connection interfaces will be included in 
your application system. In order to exclude a system call from one of 
the non-file/connection interfaces, delete the metacharacter of the 
associated macro call (%), and replace it with the comment character 
(;). By doing this, you change the macro call into a comment and prevent 
the assembler from evaluating it. Any or all of the system calls shown 
in Figure 9-2 can be excluded in this manner. 



name itable 

$inclu3e(:fl:itabie.inc) 
Reject 

; *?on-Fi le-Connection Interfaces 

. 

9 

t 

? Parameter Interlace; 

lro.create.user 

% r q „ i n s p e c t . u s <* r 

%rq_del ete.user 

% r a _ s e t _ <i e f a u 1 1 _ u s e r 

%rq_aet, default. user 

^ra_set„defauit_r>refix 

%rq_qet_defaui.t«.Dre£ix 

Configuration Interface: 

%rq«,a_DnYsical..at tach_device 
% r a. a„nnysi cai_detach.de vice 



Figure 9-2. Non-File /Connect ion Interface Configuration Values 
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Power-Fail Interface: 

%ra_nower„down 

%ro-oower.up 

Time interface: 

?-rq-.set«time 
%ra„qet„time 



Figure 9-2. Non-File Connection Interface Configuration Values 

(continued) 



SELECTING THE FILE /CONNECTION INTERFACE FEATURES (ITABLE.A86) 

The file/connection interface is the primary programmatic interface to 
the Basic I/O System, through which jobs manipulate connections and 
perform I/O. It provides the support for the file types available to the 
Basic I/O System user: named files, stream files, and physical files. 
This support is in the form of a file driver for each of these file types, 

ITABLE.A86 contains information about all of the file drivers supplied 
with the Basic I/O System. If you do not modify ITABLE.A86, all of the 
system calls associated with the file /connection interface will be 
included in your application system. By modifying this file, you can 
eliminate entire file drivers or change the number of system calls 
supported by each driver. ITABLE.A86 contains two types of data 
pertaining to file drivers. 

• File driver global data 

• File driver tables 

The following sections discuss how to modify this data in order to 
provide appropriate file driver support for your system. 



FILE DRIVER GLOBAL DATA 

The file driver global data consists of a group of macro calls which 
provide parameters used by all file drivers in your Basic I/O System. 
Figure 9-3 illustrates the portion of ITABLE.A86 which contains this 
global data. The values shown in this figure are contained in the 
released version of ITABLE.A86 and are the suggested defaults. 
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rtttiitt*tittttf*tttritt'trtrt'i'trttirt'rrr>r'r*t**ri*i*tr?ip*t*t 



; Define file-driver global data 



ri*tttttifi»itifri*t*iiitrifttr**r'fftrt*ir*i*'**t*r***t*tr**if$*i 



%num_file..drivers(4) 
%attach_device,-task_prlo(i2y) 
%timer-task«.pri 0(129) 



Figure 9-3. File Driver Global Data Parameters 



The following paragraphs discuss each of the macros shown in Figure 9-3. 
You can change the parameters of these macro calls from their default 
settings in order to reflect your individual Basic I/O System 
requirements. 



%NUM FILE DRIVERS 



%ATTACH DEVICE TASK PRIO 



This macro declares the number of file 
drivers in your Basic I/O System. 
Associated with each file driver is a file 
driver number. Use the largest file 
driver number in your system as the value 
for this parameter. Intel-supplied file 
drivers are numbered as follows: 

driver number 

Physical files 1 
Stream files 2 
Named files 4 

This macro declares the priority of the 
attach-device task. This task receives 
all requests to attach devices (via 
PHYSICAL$ATTACH$DEVICE). When the 
attach-device task receives such a 
request, it creates another task which 
actually handles the request. The second 
task's priority is one less than the 
priority of the task which called 
PHYSICAL$ATTACH$DEVICE. Thus the second 
task has a slightly higher priority. 
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%TIMER TASK PRIO 



This macro declares the priority of the 
timer task. This task manages the 
time -of -day clock for the Basic I/O 
System. Its priority can impact its 
performance and the Basic I/O System 
behavior. If the priority is set too low, 
the timer task may not get to run as often 
as it needs and the clock will slip. If 
the priority is set too high, the timer 
task may take machine cycles away from 
high priority tasks. 



I 



FILE DRIVER TABLES 

Associated with each file driver are two tables of procedure entry points 
and a macro call, which define the contents of the file driver. 
ITABLE.A86 contains this information for each of the Intel-supplied file 
drivers: the physical, stream, and named file drivers. 

The macro, named %FILE_DRIVER_INFO, supplies parameters that are of use 
to the particular file driver. This manual does not define these 
parameters; therefore you should not modify any of the macro calls unless 
you are excluding an entire file driver (discussed later in this section). 

One of the tables, the request table, lists the entry points of the 
procedures directly associated with the system calls of that file driver 
(for example, the REQREAD procedure is associated with the A$READ system 
call). These routines are called by user tasks. 

The other table, the I/O service (or ios) table, lists the entry points 
of procedures that are ultimately called to service requests generated by 
procedures in the request table. The procedures in an ios table are 
called by Basic I/O System routines. 

ITABLE.A86 provides the request tables and the ios tables in the form of 
two assembly language structures, REQ_FILE_DRIVER and IOS_FILE_DRIVER. 
The REQ_FILE_DRIVER structure defines the request table and the 
IOS_FILE_DRIVER table defines the ios table. The definitions for these 
structures are contained in the file ITABLE.INC, which is available on 
the Basic I/O System release diskette. The configuration file contains 
an $INCLUDE statement for this file, which includes it in the assembly of 
the configuration file. 

Figure 9-4 shows the portion of ITABLE.A86 that contains the 
%FILE_DRIVER_INFO call, the request table, and the ios table for the 
physical file driver. 
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Physical files: File-oriver Number 1 



• •••••••••••••••••••••••■•••••••••••••••••••••••••••••♦•••••••••••J 

ttttltttttii$fttt*tti'l*ttitiff*t*itt»til'tftrit*it*ttf*ttt*r*trtt* 



f ile_drlver_iPfo(false, 14, bl2, 20) 
Request part: 



table sequent 
file«driver < 

reacreateflle, 



req 
reo 
& 

& 

& 

& 

& 
& 

& 
& 

& 
& 

req. table 



reqattachf He, 
readetachf He, 



eqopen, 

eqclose, 

eqread, 

eqwrite, 

eqseek, 

eqphyssnecial, 
enconnectlonstatus , 
eat ilestatus, 
eage t na t he omponent. 



rqSas 
Peser 
rqSas 
Reser 
rq$a$ 
rq$a$ 
Reser 
rqsaS 
Reser 
rqsas 
rqsaS 
rqSas 
rqSas 
rqsaS 
rqsaS 
rq$a$ 
rqsaS 
rq$a$ 
rqsaS 
rq$a$ 
rqSas 
rq$a$ 
rqsa$ 
rq$a$ 



crea 

ved 

atta 

ved 

dele 

crea 

ved 

dele 

ved 

rena 

cban 

ODen 

clos 

read 

writ 

seek 

trun 

spec 

gets 

gets 

gets 

gets 

gets 

sets 



te$f ile 

chsfile 

tesconnectioh 
te$directory 

te$f ile 

me$f ile 
gesaccess 



cate 

ial 

connections stat us 

f ilesstatus 

path$component 

directorySentry 

extensionsdata 

extensionsdata 



ends 



Figure 9-4. Physical File Driver Tables 



9-8 



CONFIGURING THE BASIC I/O SYSTEM 



I/O System part: 



table 

f ile-driver 



los 
los 

s, 

& 
& 

& 
& 

ios.tabie 



segment 
< 

r 

commonlotask, 
physupdate, 
attacnpnysicalf ile, 
attacnmysicalfile, 



Dnysread, 

Dhvswrl te, 

onysseek, 

onysspectal , 

attacnphysicaldevice, 

commondetachdevice, 

pnvsopen, 

nnvsciose, 

commonoet conns t , 

pnvsoet t ilest , 

# 



pnvsaetpath, 

r 
t 

nnysdetacnf ile 
ends 



File-driver init 

I/O (connection) Task 

Update 

Attacn File 

Create Fixe 

Chanae Access (non-null path) 

Delete (non-null path) 

Read 

write 

Seek 

Special 

Attach Device 

Detach Device 

open 

Close 

Get Connection status 

Get File Status 

Get Extension Data 

set Extension Data 

Chanae Access (null path) 

Delete (null path) 

Rename 

Get Path component 

Get Directory Entry 

Truncate 

Detacn File 



Figure 9-4. Physical File Driver Tables (continued) 



Figure 9-5 shows the portion of ITABLE.A86 that contains the 
%FILE_DRIVER_INFO call, the request table, and the los table for the 
stream file driver. 
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? Stream-Flies 



; ? ; ? ; ? ; ; ; ? ; ; ; ? ; • ; • ; ; ; ? ; 

File-Driver Number 2. 






%f lle«drIver-info(false, 16, 512, 20) 
? Request part: 

req-table seoment 
req.f ile^driver < 

& 

& 

& 
& 
& 

& 

& 

& 
& 

& 

& 

& 

&> 

req_table en<is 



reacreatef lie, 
renattachf lie, 
reqdetachflie, 



reoae l e t e s t.r f i l e , 

reqopen, 
reqclose, 
reqread, 
reowrite, 

r 

reqstrspeclal , 
reqconnectionstatus, 
reof iiestatus, 
reqgetpathcomponent , 



rqSaScreatesf i] e 

Reserved 

rq$a$attach$f ile 

Reserved 

rq$a$ deletes connect ion 

rq$a$create$directory 

Reserved 

rq$a$delete$f ile 

Reserved 

rqSaSrenaroesf i] e 

rq$a$ changes access 

rq$a$ODen 

rq$a$close 

rq$a$read 

rq$a$write 

rqSasseek 

rq$a$truncate 

rqsaSsoecial 

rq$a$get$connect ions status 

rqSaSgets files status 

rq$a$get$path$cot*ponent 

rqSaSgetSdl rectory Sen try 

rqSa$ get sex tensions data 

rqSaS set Sex tens ionSaata 



Figure 9^-5. Stream File Driver Tables 
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I/O System part: 



ios 
tos 

s, 

& 

& 
& 
& 

& 

& 
£ 

ios_table 



table 
file. driver 



segment 
< 

nullfdlntt, 
commonJotasK, 

attacnstreamf ile, 
createstreamfile, 

r 

strread, 
strwrite, 

strsnecial , 

attachstreamdevice, 

coromondetacndevice, 

stropen, 

strclose, 

commonqe t conns t , 

strgetf ilest, 



strdeiete, 



strgetpath, 



strdetachf ile 



ends 



Pile-driver init 

T/n (connection) Task 

Update 

Attacn File 

Create File 

Cnanqe Access (non-null path) 

Delete (non-null path) 

Read 

Write 

Seek 

Special 

Attacn Device 

Detach Device 

open 

Close 

Get Connection Status 

Get File status 

Get Fxtenslon Data 

Set Extension Data 

Chanoe Access (null path) 

Delete (null path) 

Rename 

Get Path Component 

Get Directory Fntrv 

Truncate 

netacn File 



Figure 9-5. Stream File Driver (continued) 



Figure 9-6 shows the portion of ITABLE.A86 that contains null structures 
for the reserved file driver, driver 3. You can use structures like 
those contained in Figure 9-6 to exclude any other file driver from your 
application system. To do this, replace the %FILE_DRIVER_INFO call and 
the REQ_FILE_DRIVER and IOS_FILE_DRIVER structures associated with that 
driver with null structures of the following form: 



Ml 
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%FILE_DRI VERJNFO (0,0,0,0) 

REQ_TABLE SEGMENT 

REQ_FILE_DRIVER < > 
REQJCABLE ENDS 

IOS_TABLE SEGMENT 

IOS_FILEJDRIVER < > 
IOSJCABLE ENDS 

Even if you make changes to the structures, you must maintain them in the 
order that they appear in the released Basic I/O System configuration 
file. 



• tilttfttlititrt'irt'l't'ttltt'l't'ltl't'l't'trt'ttttirittrffif 

? File-Driver Numoer 3: Reserved. 

w 

tl*tlt*9*1tt*tf\*}*itt'l*trt99fttlttf199'l*ttt*9t'itlttlfltft*1i 

• 

%f ile_driver_inf o(Q,0, 0,0) 

Request part: 

req, table seament 

req.f ilcdriver <> 
rentable ends 

I/O System part: 

ios-table segment 

ios«.file. driver <> 
ios. table ends 

Select 



Figure 9-6. Reserved File Driver Tables 



Figure 9-7 shows the portion of ITABLE.A86 that contains the 
%FILE_DRIVER_INFO call, the request table, and the ios table for the 
named file driver. 
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t 

? Named Files: File-oriver Number 4. 



;? 



rrrrt'trt'l't 



l * t * I 



%f ile«driver-info(true, ?6, 10?4, 54) 
7 Request part: 



req. table 


senment 




req.f lie- driver 


< 




& 


reacreatef t le, 


? rq$a$create$f lie 


s. 


t 


r Peserved 


& 


reqattachfiie, 


r rq$a$attach$f ile 


& 


t 


• Reserved 


& 


rendetachf ile, 


r rq$a$delete$connection 


& 


reacreatedirectory , j 


• rq$a$create$directory 


& 


t 


', Reserved 


& 


readeletef ile, , 


• rq$a$delete$f ile 


& 


» < 


', Reserved 


& 


rearenameiile, 


• rqsasrename$f ile 


£ 


reqchangeaccess, 


• rq$a$change$access 


& 


reaonen, 


• rq$a$ooen 


& 


r enclose, 


• rq$a$close 


& 


rearead, 


• rqsa$read 


& 


reowrite, , 


• rq$as*rite 


& 


reqseefc, , 


• rq$a$seek 


St 


reatrunc, 


• rqsastruncate 


& 


reonumspecial , , 


• rq$a$special 


& 


reaconnectionstatus, 


• rq$asget$connectionsstatus 


s> 


renfilestatus , : 


• rqsa$get$f iiesstatus 


& 


reqgetcathcomponent , 


• rqsa$get$path$component 


& 


rengetdirectorventry , \ 


• rq$a$get$directory$entry 


& 


reonumqetextensiondata, '> 


• rqsasgetsextensionsdata 


req. table 


reonumsetextensiondata j 


• rq$a$set$extension$aata 


e 1 1 >i s 





Figure 9-7. Named File Driver Tables 
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I/O System part; 



ios-tabie 


seament 


los. file-driver 


< 


common! otasfc. 


& 


numuodate, 


& 


attacnnamedf ile, 


& 


createnamedtile, 


K, 


namedchangeaccess * 


& 


nameddelete, 


& 


numread, 


& 


numwrite, 


& 


numseek , 


& 


numspecial, 


& 


attacnnameddevice, 


& 


comrnondetachdevice. 


& 


numopen , 


& 


numclose, 


& 


commonaetconnst , 


& 


numgetf iiest, 


& 


namyetextdata, 


& 


namsetextdata, 


& 


namchaccess , 


& 


namdeiete, 


& 


namrename , 


£ 


namgetDdtn, 


& 


namdlrentry , 


& 


numtrunc, 


& 


numdetachf ile 


&> 




los^tabie 


ends 



File-driver init 

I/O (connection) Task 

Update 

attach File 

Create File 

Chanoe Access (non-null oat 

Delete (non-null path) 

Read 

Write 

seeK 

Special 

Attach Device 

Detach Device 

Open 

Close 

Get Connection status 

Get File Status 

Get Extension Data 

Set Extension Data 

Change Access (null path) 

Delete (null path) 

Rename 

Get Path Component 

Get Directory Fntry 

Truncate 

Detach File 



Figure 9-7. Named File Driver Tables (continued) 



You can modify the file driver tables in one of two ways. If you want to 
exclude an entire driver from your Basic I/O System, substitute null 
structures for its %FILE_DRIVER_INFO call and its REQ_FILE_DRIVER and 
IOS_FILE_DRIVER structures in ITABLE.A86. However, if you want to 
eliminate one or more system calls from a file driver but still include 
the file driver as part of your Basic I/O System, delete the procedure 
names associated with the affected system calls from both the 
REQ FILE DRIVER structure and the IOS FILE DRIVER structure. 
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Replace the procedure names in the REQ_FILE_DRIVER structure with the 
name NOTCONFIGURED. Replace the procedure names in the IOS_FILE_DRIVER 
structure with commas. This causes the Basic I/O System to return the 
E$NOT$ CONFIGURED exception code to any task that attempts to invoke one 
of the eliminated system calls. Table 9-1 lists the system calls and 
associated procedure names for the physical file driver. Table 9-2 lists 
the system calls and associated procedure names for the stream file 
driver. Table 9-3 lists the system calls and the associated procedure 
names for the named file driver. 



I 



Table 9-1. Physical File Driver System Calls and Procedure Names 



SYSTEM CALL 


REQ FILE DRIVER 
NAME 


IOS FILE DRIVER 
NAME 


A$CREATE$FILE 


REQCREATEFILE 


ATTACHPHYS ICALF ILE 
(the second one) 


A$ATTACH$FILE 


REQATTACHFILE 


ATTACHPHYSICALFILE 
(the first one) 


A$OPEN 


REQOPEN 


PHYSOPEN 


A$SEEK 


REQSEEK 


PHYSSEEK 


A$READ 


REQREAD 


PHYSREAD 


A$WRITE 


REQWRITE 


PHYSWRITE 


A$SPECIAL 


REQPHYSSPECIAL 


PHYSSPECIAL 


A$ CLOSE 


REQCLOSE 


PHYSCLOSE 


A$GET$CON- 
NECTION$STATUS 


REQCONNECTIONSTATUS 


PHYSGETCONNST 


A$GET$FILE$STATUS 


REQFILESTATUS 


PHYSGETFILEST 


A$GET$PATH$COM- 
PONENT 


REQGETPATHCOMPONENT 


PHYSGETPATH 


A$DELETE$CON- 
NECTION 


REQDETACHFILE 


PHYSDETACHFILE 
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Table 9-2. Stream File Driver System Calls and Procedure Names 



SYSTEM CALL 


REQ FILE DRIVER 
NAME 


IOS FILE DRIVER 

NAME 


A$CREATE$FILE 


REQCREATEFILE 


CREATESTREAMFILE 


A$ATTACH$FILE 


REQATTACHFILE 


ATTACHSTREAMFILE 


A$OPEN 


REQOPEN 


STROPEN 


A$READ 


REQREAD 


STRREAD 


A$WRITE 


REQWRITE 


STRWRITE 


A$SPECIAL 


REQSTRSPECIAL 


STRSPECIAL 


A$CLOSE 


REQCLOSE 


STRCLOSE 


A$GET$CON- 
NECTION$ STATUS 


REQCONNECTIONSTATUS 


STRGETCONNST 


A$GET$FILE$STATUS 


REQFILESTATUS 


STRGETFILEST 


A$GET$PATH$COMPONENT 


REQGETPATHCOMPONENT 


STRGETPATH 


A$DELETE$CONNECTION 


REQDETACHFILE 


STRDETACHFILE 


A$DELETE$FILE 


REQDELETESTRFILE 


STRDELETE 
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Table 9-3. Named File Driver System Calls and Procedure Names 



..... ._ 

SYSTEM CALL 


REQ FILE DRIVER 

NAME 


IOS FILE DRIVER 
NAME 


A$CREATE$FILE 


REQCREATEFILE 


CREATENAMEDFILE 


A$ATTACH$FILE 


REQATTACHFILE 


ATTACHNAMEDFILE 


A$CREATE$DIRECTORY 


REQCREATEDIRECTORY 


CREATENAMEDFILE 


A$ CHANGE $ ACCESS 


REQCHANGEACCESS 


NAMEDCHANGEACCE S S 
NAMCHACCESS 


A$RENAME$FILE 


REQRENAMEFILE 


NAMRENAME 


A$OPEN 


REQOPEN 


NUMOPEN 


A$SEEK 


REQSEEK 


NUMSEEK 


A$READ 


REQREAD 


NUMREAD 


A$WRITE 


REQWRITE 


NUMWRITE 


A$ SPECIAL 


REQNUMSPECIAL 


NUMSPECIAL 


A$CLOSE 


REQCLOSE 


NUMCLOSE 


A$GET$CON- 
NECTION$ STATUS 


REQCONNECTIONSTATUS 


NUMGETCONNST 


A$GET$FILE$ STATUS 


REQFILESTATUS 


NUMGETFILEST 


A$GET$DI- 
RECTORY$ENTRY 


REQGETDIRECTORYENTRY 


NAMDIRENTRY 


A$GET$PATH$COMPONENT 


REQGETPATHCOMPONENT 


NAMGETPATH 


A$DELETE$CONNECTION 


REQDETACHFILE 


NUMDETACHFILE 


A$TRUNCATE 


REQTRUNC 


NUMTRUNC 


A$DELETE$FILE 


REQDELETEFILE 


NAMEDDELETE 
NAMDELETE 


A$GET$EXTENSION$DATA 


REQNUMGETEXTENSIONDATA 


NAMGETEXTDATA 


A$ SET$EXTENSION$DATA 


REQNUMSETEXTENS IONDATA 


NAMSETEXTDATA 
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In addition to the file driver tables shown in Figures 9-4, 9-5, 9-6, and 
9-7, ITABLE.A86 also contains external declarations for all the symbols 
referenced by the REQ_FILEJDRIVER and the IOS_FILE_DRIVER structures. If 
you modify these structures to exclude system calls from your Basic I/O 
System, you can eliminate the EXTRN statements for the excluded procedure 
names, as long as these procedure names are not referenced by other file 
driver structures. However, make sure that all references to a procedure 
name have been eliminated before removing its EXTRN statement. 



Example: 

To remove the A$RENAME$FILE system call from the named file driver, 
replace the REQRENAMEFILE procedure name in the named file driver 
REQ_FILE_DRIVER structure with RQNOTCONFIGURED. Also replace the 
NAMRENAME procedure name in the named file driver IOS_FILE_DRIVER 
structure with a comma. Then remove the EXTRN statements for these names 
from the configuration file. 



SELECTING FEATURES (ITABLE.A86) 

Figure 9-8 shows the part of ITABLE.A86 that selects features of the 
Basic I/O System. These features are selected with macro calls, much in 
the same way as the non-file/connection interfaces. However, unlike the 
non- file /connect ion interface, features are selected by excluding the 
corresponding macro call from ITABLE.A86. In order to include a macro 
call from ITABLE.A86 (and thus exclude the feature), replace the 
semicolon (;) at the beginning of the corresponding macro call with a 
percent-sign (%). 



• •••'•♦•••••••••••••♦•••a* 



Define any features to be configured. 



;aummy_tl;T»er 
?no-create«.taise 
;no-truncate 
;no_ai locate 



Figure 9-8. Basic I/O System Features 
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The following paragraphs discuss each of the macros shown in Figure 9-8. 



%DUMMY TIMER 



%NO_CREATE 
FALSE 



%N0 TRUNCATE 



%N0 ALLOCATE 



The presence of this macro call causes the Basic I/O 
System to be assembled without timing facilities. 
Without timing facilities, the Basic I/O System fills 
in all time fields with a zero value and saves the 
overhead of maintaining a timer. Also, without timing 
facilities you can debug your application system in 
single-step mode using the iSBC 957A monitor, because 
the system is not constantly servicing clock 
interrupts. However, if you include the %DUMMY_TIMER 
macro call, you should exclude the GET$TIME and 
SET$TIME system calls from your Basic I/O System. 

If you exclude the %DUMMY_TIMER call from ITABLE.A86, 
the timing facilities of the Basic I/O System are 
included in your application system. 

The presence of this macro call causes the Basic I/O 
System to be assembled without the ability to create 
connections to existing files with the CREATE$FILE 
system call. In particular, if this macro is present, 
the user cannot call CREATE$FILE with the must$create 
parameter set to false. If the Basic I/O System 
encounters such a call, it returns the E$SUPPORT 
exception code. This option implies that CREATE $FILE 
can only be used to create connections to nonexistent 
files. Refer to the iRMX 86 BASIC I/O SYSTEM 
REFERENCE MANUAL for detailed information concerning 
the CREATE$FILE system call. 

The presence of this macro call causes the Basic I/O 
System to be assembled without the TRUNCATE system 
call and its associated modules. The presence of this 
macro call also requires the presence of the 
%NO_CREATE_FALSE call, since setting the must$create 
parameter of CREATE$FILE to false requires the ability 
to truncate the file (refer to the iRMX 86 BASIC I/O 
SYSTEM REFERENCE MANUAL). This macro call also 
requires that you omit the TRUNCATE and DELETE$FILE 
system calls from your application system by removing 
their entries from the file driver tables (refer to 
the "File Driver Tables" section of this chapter). 

The presence of this macro call causes the Basic I/O 
System to be assembled without the ability to extend 
files beyond their current end-of-file boundaries. 
This macro call requires that you omit the CREATE$FILE 
and CREATE$ DIRECTORY system calls from your 
application system by removing their entries from the 
file driver tables (refer to the "File Driver Tables" 
section of this chapter). You should not include this 
macro call in ITABLE.A86 unless the users of the Basic 
I/O System only read from existing files on named-file 
volumes. However, inclusion of this macro call 
reduces the size of the Basic I/O System. 
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DESCRIBING THE I/O DEVICES (IDEVCF.A86) 

An I/O device consists of a controller and one or more units. A device 
driver services each I/O device. In order to include I/O devices in your 
system, you must provide specific information about devices, units, and 
device drivers as well as general information about all devices in the 
system. The specific information is provided in the form of device-unit 
information blocks (DUIBs). The general information is provided in the 
form of a macro call. The Basic I/O System configuration file, 
IDEVCF.A86, contains several DUIBs for standard devices as well as the 
general information for these devices. 

Using the information presented in this chapter as a guide, you must 
modify IDEVCF.A86 so that it describes the devices attached to your 
system. 

Before presenting the specific information that you need in order to 
modify the configuration file, this chapter describes the terms device 
number, unit number, and device-unit number, since you must specify each. 



DEVICE NUMBERING 

Figure 9-9 contains a simplified drawing of three I/O devices in a 
system. The device numbers of these three devices are 0, 1, and 2, as 
shown. The device number represents the device as a whole. A unit 
number uniquely identifies a unit within a device (such as a single disk 
drive of a multi-drive device). Notice that the unit numbers of one 
device can duplicate the unit numbers of another. A device -unit number 
uniquely identifies a unit of a device among all the units of all the 
devices. Device-unit numbers are not duplicated. 



DEVICE o 



DEVICE 1 



DEVICE 2 



CONTROLLER 












UNIT 




UNIT 1 


DEVICE- 
UNIT 


DEV 
UN 


ICE- 
T 1 





CONTR 


OLLER 




UN 


T 




UNI 


T 1 




UN 


T 2 


DEVICE- 




DEVICE- 




DEVICE- 


UNIT 2 




UNIT 3 




UNIT 4 



CONTF 


IOLLER 




UN 


T 






DEVICE- 






UNIT 5 





Figure 9-9. Device Numbering 



9-20 



CONFIGURING THE BASIC I/O SYSTEM 



Before creating your Basic I/O System configuration file, assign each 
device in your system a device number. Likewise, assign each unit a unit 
number and a device-unit number. The order of assignment is not 
important (with the exception of the unit number), as long as it is 
consistent with the definitions supplied previously, and the numbering of 
devices, units, and device-units begins with 0. The device driver uses 
the unit number to select the correct unit on the device. Make sure that 
if you have two of the same type of controller (such as two iSBC 204 
controllers), assign each of them a separate device number. 



DEVICE-UNIT INFORMATION BLOCKS 

A device-unit information block (DUIB) is a block of information that you 
must supply for each device-unit in your system. You can provide this 
information by entering DEFINE_DUIB assembly language structures into the 
Basic I/O System configuration file. The definition of this structure is 
contained in file IDEVCF.INC, which is available on the Basic I/O System 
release diskette. IDEVCF.A86 contains an $INCLUDE statement for this 
file, which includes it in the assembly of the configuration file. The 
format of the DEFINE DUIB structure is as follows: 



DEFINE DUIB < 


& 


dev name, 


& 


file drivers, 


& 


functions, 


& 


flags, 


& 


dev gran, 


& 


low dev_size, 


& 


high dev size, 


& 


device_number , 


& 


unit number, 


& 


device unit number, 


& 


init io, 


& 


finish io, 


& 


queue io, 


& 


cancel io, 


& 


device info, 


& 


unit info, 


& 


update timeout, 


& 


num buffers, 


& 


priority 


& 


> 


where: 




dev 


name N 



Name of the device-unit. Specify this name as 
a string of 14 characters or less, surrounded 
by single quotes. This name is supplied to the 
PHYSICAL$ATTACH$DEVICE system call in order to 
identify the device to be attached. For 
example, the name f F0' could be used as the 
name of an iSBC 204 unit. 
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file_drivers WORD specifying file driver validity. Setting 

bit number i of this word implies that file 
driver number i+1 can attach this device-unit. 
Clearing bit number i implies that file driver 
number i+1 cannot attach this device-unit. 
Bits are numbered from right to left, starting 
with bit 0. Legitimate file drivers and their 
associated bit numbers include: 

File Driver Bit Number 
physical 
stream 1 

named 3 

The remainder of the word must be set to zero. 

functions WORD specifying I/O function validity. Setting 

bit number i of this word implies that this 
device-unit supports function number i. 
Clearing bit number i implies that the 
device-unit does not support function number 
i. Bits are numbered from right to left, 
starting with bit 0. Legitimate functions and 
their numbers include: 

Function Bit Number 

F$READ 

F$WRITE 1 

F$SEEK 2 

F$ SPECIAL 3 

F$ATTACH$DEV 4 

F$DETACH$DEV 5 

F$0PEN 6 

F$ CLOSE 7 

Bits 4 and 5 must always be set. Every device 
driver requires these functions. Bits 8-15 of 
this word must be set to zero. 

flags BYTE specifying characteristics of diskette 

devices. The significance of the bits is as 
follows: 

bit meaning 

Reserved 

1 = single density; 1 = double 

density 

2 0= single sided; 1 = double sided 
3-7 Reserved 
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dev gran 



WORD specifying the device granularity in 
bytes. This parameter is generally used for 
random access devices (described later in this 
section). It specifies the minimum number of 
bytes of information that the device reads or 
writes in one operation, or the sector size of 
the device. You should set this value equal to 
the volume granularity specified when the 
volume was formatted. For example, for an iSBC 
204 or iSBC 206 unit you could specify 128 or 
512. 



low dev size 



high dev size 



Low-order WORD of the device storage capacity, 
in bytes. 

High-order WORD of the device storage capacity, 
in bytes. 



device number 



BYTE specifying the number of the device with 
which this DUIB is associated. Refer to the 
"Device Numbering" section of this chapter for 
more specific information. 



unit number 



BYTE specifying the unit number of the 
device-unit associated with this DUIB. This 
number identifies one out of a possible several 
units of a device. Refer to the "Device 
Numbering" section of this chapter for more 
specific information. 



device unit number 



BYTE specifying the number of the device-unit 
associated with this DUIB. Refer to the 
"Device Numbering" section of this chapter for 
more specific information. 



init io 



WORD specifying the offset in the code segment 
of this unit's Initialize I/O device driver 
procedure. Refer to Table 9-4 for special 
information concerning common and random access 
drivers. The GUIDE TO WRITING DEVICE DRIVERS 
FOR THE iRMX 86 I/O SYSTEM contains additional 
information about this procedure. You must 
also place an EXTRN statement for the init_io 
parameter in the configuration file. 



finish io 



WORD specifying the offset in the code segment 
of this unit's Finish I/O device driver 
procedure. Refer to Table 9-4 for special 
information concerning common and random access 
drivers. The GUIDE TO WRITING DEVICE DRIVERS 
FOR THE iRMX 86 I/O SYSTEM contains additional 
information about this procedure. You must 
also place an EXTRN statement for the finish_io 
parameter in the configuration file. 
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queue 10 



cancel io 



WORD specifying the offset in the code segment 
of this unit's Queue I/O procedure. Refer to 
Table 9-4 for special information concerning 
common and random access drivers. The GUIDE TO 
WRITING DEVICE DRIVERS FOR THE iRMX 86 I/O 
SYSTEM contains additional information about 
this procedure. You must also place an EXTRN 
statement for the queue_io parameter in the 
configuration file. 

WORD specifying the offset in the code segment 
of this unit's Cancel I/O procedure. Refer to 
Table 9-4 for special information concerning 
common and random access drivers. The GUIDE TO 
WRITING DEVICE DRIVERS FOR THE iRMX 86 I/O 
SYSTEM contains additional information about 
this procedure. You must also place an EXTRN 
statement for the cancel_io parameter in the 
configuration file. 



device info 



POINTER to a device information table for this 
device. Specify for this parameter if the 
driver for the associated device does not need 
this field. Refer to the "Device and Unit 
Information" section of this chapter for 
specific information concerning the 
device-information table. 



unit info 



POINTER to a unit information table for this 
unit. Specify for this parameter if the 
driver for the associated unit does not need 
this field. Refer to the "Device and Unit 
Information" section of this chapter for 
specific information concerning the 
unit-information table. 



update timeout 



WORD specifying the number of clock intervals 
(defined during Nucleus configuration; see 
Chapter 6) that the I/O system waits after 
completing an I/O request before updating file 
data structures on the volume. After a request 
on a connection has been completed, the Basic 
I/O System updates the data structures on the 
volume unless a new request is made before this 
timeout value expires. If you specify a zero 
value for this parameter, the Basic I/O System 
updates the structures during each request. A 
value of OFFFFH indicates that updates occur 
only when the device is detached. 

When your Basic I/O System is in the debugging 
stages, you should specify a zero timeout 
value. Otherwise it is recommended that you 
specify a value for this parameter that when 
multiplied by the length of a clock interval 
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yields an update timeout value of about 1 
second, unless your system can maintain disk 
integrity with the OFFFFH value. You can 
adjust the update_timeout value in conjunction 
with the num_buffers parameter to increase the 
performance of the Basic I/O System when 
dealing with this unit. 

num_bu.ffers WORD which specifies whether a device is a 

random access device and, if it is, specifies 
how many buffers the device uses. If this 
parameter is nonzero, it specifies that the 
device is of the random access variety and 
indicates the number of buffers this unit will 
have for blocking and deblocking I/O requests. 
Each sector is one buffer plus 16 bytes long. 
The Basic I/O System uses these buffers to 
store partial blocks of data when I/O requests 
do not start on sector boundaries or transfer 
counts are not multiples of the device 
granularity. In most application systems, 4 is 
an optimal value for this parameter. A value 
of for this parameter indicates that the 
device is not a random access device. 

priority BYTE specifying the priority of the Basic I/O 

System service task for the device. 



You must specify a DEFINE_DUIB structure for each device-unit in the 
system. However, you can specify more DUIB structures than 
device-units. Each DUIB must have a unique name (specified with the 
dev_name parameter) but more than one DUIB can apply to the same 
device-unit. Different DUIBs can be used to specify different 
characteristics for the same device-unit. Therefore, different device or 
unit characteristics can be selected at run-time when the DUIB is 
associated with the device-unit (such as choosing between single- and 
double-density diskettes, for example). This is done with the 
A$PHYSICAL$ATTACH$DEVICE system call. You must arrange all of the DUIBs 
contiguously in your configuration file. Do not place any other code 
between the DEFINEJDUIB structures. 

The Basic I/O System supports the notion of common and random access 
drivers, providing a set of support routines for these drivers. When you 
use common and random access drivers you must reference these 
Intel-supplied procedures in the DEFINE_DUIB structure. The DEFINE_DUIB 
parameters and the values which you must enter are listed in Table 9-4. 
The GUIDE TO WRITING DEVICE DRIVERS FOR THE iRMX 86 I/O SYSTEM discusses 
common and random access device drivers in more detail. 



9-25 



CONFIGURING THE BASIC I/O SYSTEM 



Table 9-4. Common and Random Access Driver DUIB Values 



DEFINE_DUIB 
Parameter 


Common and Random Access Driver 
Parameter 


init_io 


INITIO 


finish_io 


FINISHIO 


queue_io 


QUEUE 10 


cancel_io 


CANCELIO 



Former releases of the Basic I/O System provided two versions of the 
procedures listed in Table 9-4, one version for common drivers and one 
version for random access drivers. The random access procedures had the 
names listed in Table 9-4, but with the characters "RAD" as a preface. 
Now, the procedures listed in Table 9-4 provide support for both types of 
drivers. However, to be compatible with previous releases, the "RAD" 
names are still supported. If you are using a configuration file created 
in a previous release, you need not modify it to update these names. 

IDEVCF.A86 contains DEFINE_DUIB structures for several standard devices. 
Figure 9-10 shows one of these structures. 



; Snugart 204, 


unit 1 


def ir»e_duib 


< 


& 


'F1 ', 


& 


OOBH, 


& 


OFFH, 


& 


00H, 


& 


129,. 


& 


Ok;9Q0ri,03H, 


& 


f 


& 


1, 


& 


1, 


& 


initio, 


& 


finlshio, 


& 


nueueio, 


& 


cancelio, 


& 


dinto.204, 


& 


uin£o_sh>igart , 


& 


100, 


& 


fi r 


& 


129 


&> 
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Device 
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updatestimeout 
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priority 



Figure 9-10. Example DUIB Contained in IDEVCF.A86 
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The DUIB in Figure 9-10 defines an iSBC 204 unit. The name of this DUIB 
is Fl. This name should be used when making an A$PHYSICAL$ATTACH$DEVICE 
system call. The parameters of the DUIB describe the unit as follows: 

• The OBH value for the file_drivers parameter indicates that file 
drivers one, two, and four can attach this device-unit (bits 0, 
1, and 3 are set). 

• The OFFH value for the functions parameter indicates that all 
eight functions are valid for this device-unit (bits 0-7 are set). 

• The 00H value for the flags parameter indicates that the drive is 
a single-density, single-sided diskette drive. 

• The 0E900H value for the low_dev_size parameter and the 03H value 
for the high_dev_size parameter indicate a storage capacity of 
3E900H bytes, or 256256 decimal bytes. 

• The values for the device_number , unit_number, and 
device_unit_number parameters indicate that this DUIB applies to 
device-unit 1, which is unit 1 of device 0. 

• The init_io, finish_io, queue_io, and cancel_io parameters 
indicate that this iSBC 204 device has a random access driver. 
These parameters contain the values listed in Table 9-4 for 
random access and common driver entry points. IDEVCF.A86 
contains EXTRN statements for these entry points. 

• The device_info and unit_info parameters indicate that this 
device has a device information table located at the address of 
symbol DINFO_204 and this unit has a unit information table 
located at the address of symbol UNIFO_SHUGART . IDEVCF.A86 
contains these tables. They are described in the next section. 



DEVICE AND UNIT INFORMATION TABLES 

The device_info and unit_info parameters of DEFINE_DUIB refer to tables 
that you must place in the configuration file which contain specific 
information that the driver needs. The format of the information in each 
table depends on the device driver. This section describes the formats 
of the device information tables and unit information tables for common 
and random access device drivers. The GUIDE TO WRITING DEVICE DRIVERS 
FOR THE iRMX 86 I/O SYSTEM contains more complete information about these 
device drivers. 



Common Device Driver Tables 

To provide device information tables for common device drivers, use the 
C0MM0N_DEV_INF0 assembly language structure. This structure is defined 
in file IDEVCF.INC, which is available on the Basic I/O System release 
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diskette. IDEVCF.A86 contains an $INCLUDE statement for this file, which 
includes it in the assembly of the configuration file. The format of the 
COMMON_DEV_INFO structure is as follows: 

COMMON DEV INFO < 



& 


level, 


& 
& 


priority, 
stack size, 


& 


data size, 


& 


num units, 


& 


device init, 


& 


device_finish, 


& 


device_start, 


& 
& 
& 


device_stop, 
device interrupt 
> 



where: 



level WORD specifying an encoded interrupt level at which 

the device will interrupt. The interrupt task uses 
this value to associate itself with the correct 
interrupt level. The values for this field are 
encoded as follows: 

bits value 

15-7 

6-4 First digit of the interrupt level (0-7) 

3 If one, the level is a master level and bits 
6-4 specify the entire level number. If 
zero, the level is a slave level and bits 2-0 
specify the second digit 

2-0 Second digit of the interrupt level (0-7), if 
bit 3 is zero. 

priority BYTE specifying the initial priority of the device's 
interrupt task. 

stackjsize WORD specifying the size in bytes of the stack for the 
user-written device interrupt procedure (and other 
procedures that .... it . calls).. This number should not 
include stack requirements for the Basic I/O 
System-supplied procedures. They add their 
requirements to this number. 

data_size WORD specifying the size in bytes of the user portion 
of the device-local data. This data is for driver use 
only. The common driver support procedures supplied 
by the Basic I/O System allocate their data in 
addition to this. 
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numjunits WORD specifying the number of units supported by the 
driver. Units are assumed to be numbered 
consecutively, starting with zero. 

device_init WORD specifying the start address of the user-written 
device initialization procedure. 

device_finish WORD specifying the start address of the user-written 
device finish procedure. 



device start 



device stop 



device_in- 
terrupt 



WORD specifying the start address of the user-written 
device start procedure. 

WORD specifying the start address of the user-written 
device stop procedure. 

WORD specifying the start address of the user-written 
device interrupt procedure. 



Depending on the actual device driver, you may have to provide additional 
fields for this structure. The GUIDE TO WRITING DEVICE DRIVERS FOR THE 
iRMX 86 I/O SYSTEM describes all fields of this structure in more detail. 

Most common device drivers do not require unit information tables. 
Therefore, make sure to set the unit_info field of the DEFINE_DUIB 
structure to zero for any device-units that use common device drivers, 
unless the particular driver requires unit information. 



Random Access Device Driver Tables 

To provide the device information tables and unit information tables for 
random access device drivers, use the RADEV_DEV_INFO and RADEV_UNIT_INFO 
assembly language structure. These structures are defined in file 
IDEVCF.INC, which is available on the Basic I/O System release diskette. 
IDEVCF.A86 contains an $INCLUDE statement for this file, which includes 
it in the assembly of the configuration file. 

The format of the RADEV_DEV_INFO structure is as follows: 

RADEV DEV INFO < 



& 


level, 


& 
& 


priority, 
stack size , 


& 


data_size, 


& 


num units, 


& 


device_init, 


& 


device_finish, 


& 
& 
& 
& 


device_start, 
device_stop, 
device interrupt 
> 
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The fields of this structure are the same as those for the 
COMMON_DEV_INFO structure and are described in the "Common Device Driver 
Tables" section of this chapter. 

Depending on the actual device driver, you may have to provide additional 
parameters for this structure. Refer to the "Device Driver Tables for 
Intel-supplied Device Drivers" section of this chapter for examples of 
this. The GUIDE TO WRITING DEVICE DRIVERS FOR THE iRMX 86 I/O SYSTEM 
describes all of the fields of this structure in detail. 



To provide the unit information table for a random access device driver, 
use the RADEV_UNIT_INFO assembly language structure. The format of this 
structure is as follows: 

RADEVJJNITJNFO < 
& track_size, 

& max_retry, 

& 

& > 

where: 

track_size WORD specifying the size in bytes of one track of a 
volume of the device. If the controller can handle 
requests that cross track boundaries, specify for this 
parameter. 

max_retry WORD specifying the maximum number of times an operation 
should be retried if an error occurs. A value of 9 is 
recommended. 

Depending on the actual device driver, you may have to provide additional 
parameters for this structure. Refer to the "Device Driver Tables for 
Intel-supplied Device Drivers" section of this chapter for examples of 
this. Also refer to the GUIDE TO WRITING DEVICE DRIVERS FOR THE iRMX 86 
I/O SYSTEM for further information about this structure. 



Device-Driver Tables for Intel-supplied Device Drivers 
Intel supplies device drivers for the following devices: 

iSBC 204 flexible disk controller 

iSBC 206 hard disk controller 

iSBC 215/iSBX 218/ ISBC 220 winchester/flexible/SMD disk controller 

iSBC 254 bubble memory controller 

iSBC 86/12A on board USART 

byte bucket 
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All you have to do in order to use these drivers is to fill out the 
DUIBs, device information tables, and unit information tables as 
described in this section. 



iSBC 204 Driver . The iSBC 204 driver is a random access driver. It 
supports the following: 

• The functions F$READ, F$WRITE, F$SEEK, F$SPECIAL, 
F$ATTACH$DEVICE, and F$DETACH$DEV. F$0PEN and F$CL0SE are 
accepted, but the driver performs no operations for these 
functions. Track formatting and volume change notification are 
supported via the F$SPECIAL function. Refer to the iRMX 86 I/O 
SYSTEM REFERENCE MANUAL for further information about these 
special functions. 

• All Intel-supplied file drivers. 

• Device granularities of 128 and 512 bytes, software selectable on 
a per-unit basis. 

• Up to four units per controller; two for each 8271 DMA chip. The 
8271 chip at chip location A4 of the iSBC 204 board is FDCO, 
controlling units and 1. The 8271 chip at chip location A6 is 
FDC1, controlling units 2 and 3. 

You must place the following values in the device information table in 
order to support the iSBC 204 driver: 

RADEV DEV INFO Field Value 



level Configuration option 

priority Configuration option 

stack_size 20 

data_size 127 

numjunits 1 through 4 

device_init I204INIT 

de vi ce_f ini sh DEFAULTFINI SH 

device_start I204START 

de vi ce_s t op DEFAULTSTOP 

device_interrupt I204INTERRUPT 

In addition, you must also append the following information to the device 
information structure: 

Type Value 

WORD Address of the I/O port which matches the 

board configuration. 

Figure 9-11 shows a device information table contained in IDEVCF.A86. 
This table is the one associated with the DUIB shown in Figure 9-10. 
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? General 


204 


Single-Density t 


dinfo.204 




radev_dev.inf o 


& 




0S8H, 


& 




8lt 


& 




20, 


& 




1 27 , 


& 




4, 


& 




U04init, 


& 




def auitf Inish, 


& 




1204start, 


& 




def aultstop, 


& 




i204interrupt 


&> 







dw 



OAOh 



level 

priority 

stack$size 

data$size 

num$units 

device$init 

devieesf inish 

device$start 

deviceSstop 

deviceSinterrupt 

I/O port base (204 specifiic 



Figure 9-11. Device Information Table for iSBC 204 Device 



IDEVCF.A86 also contains EXTRN statements for the symbols referenced in 
the Figure 9—11. 

You must supply the following information in the unit information table 
in order to support the ISBC 204 driver: 



RADEV UNIT INFO Field 



Value 



track_size 
max retry 



26 * 128 or 8 * 512 
9 (recommended) 



In addition, you must append the following information, in sequence, to 
the unit information structure: 



Type 



Value 



I 



WORD 
WORD 
BYTE 
BYTE 
BYTE 



reserved 

reserved 

step-rate for drive 

settle time for drive 

head load/unload time 



Refer to the description of the specify command in the i SBC 204 FLEXIBLE 
DISKETTE CONTROLLER HARDWARE REFERENCE MANUAL for more information about 
these values. Figure 9-12 shows a unit information table contained in 
IDEVCF.A86. This table is associated with the DUIB shown in Figure 9-10. 
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Shugart floppy unit infomation: 



uinfo_shugart radev.unlt.into < 

& 2t> * 1?8, 

& 9, 

& 

&> 

? 204 Specific: 

dw 4 

dt> 035H,0DH 

do 8 

do P 

db 039H 



; track size 

; max retry 
; reserved 



; Reserved 

? Fixed initialize values. 

; step rate 

; settle 

; cntsioad 



Figure 9-12. Unit Information Table for iSBC 204 Unit 



iSBC 206 Driver . The iSBC 206 driver is a random access driver. It 
supports the following: 

• The functions F$READ, F$WRITE, F$SEEK, F$SPECIAL, F$ATTACH$DEV, 
and F$DETACH$DEV. F$0PEN and F$CL0SE are accepted, but the 
driver performs no operations for these functions. Track 
formatting and volume change notification are supported via the 
F$SPECIAL function. Refer to the iRMX 86 I/O SYSTEM REFERENCE 
MANUAL for further information about these special functions. 

• All Intel-supplied file drivers. 

• Device granularities of 128 and 512 bytes, hardware (switch) 
selectable on a per-spindle basis. 

• Up to 16 units per controller. 

The iSBC 206 driver can support four spindles, with up to four platters 
per spindle. Units 0-3 are on the first spindle, 4-7 are on the second, 
8-11 are on the third, and 12-15 are on the fourth. Units 0, 4, 8, and 
12 are the removable platters. 

You must specify the following values in the device information table, in 
order to support the iSBC 206 driver: 



RADEV_DEVJLNFO Field 

level 
priority 



Value 

Configuration option 
Configuration option 
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RADEV DEV INFO Field Value 



stack_size 40 

data_size 16 

numjunits 1 through 16 

device_init I206INIT 

device_finish DEFAULTFINISH 

device_start I206START 

device_stop DEFAULTSTOP 

device interrupt I206INTERRUPT 



In addition, you must also append the following data to the device 
information structure: 

Type Value 

WORD Address of the I/O port which matches the 

board configuration. 



You must specify the following values in the unit information table, in 
order to support the iSBC 206 driver: 

RADEV UNIT INFO Field Value 



track_size 36 * 128 or 12 * 512 

max retry 9 (recommended) 



iSBC 215/iSBX 218/iSBC 220 Driver. The iSBC 215/iSBX 218/iSBC 220 driver 
is a random access driver. It supports the following: 

• The functions F$READ, F$WRITE, F$SEEK, F$SPECIAL, F$ATTACH$DEV, 
and F$DETACH$DEV. F$0PEN and F$CL0SE are accepted, but the 
driver performs no operations for these functions. Track 
formatting and volume change notification are supported via the 
F$SPECIAL function. Refer to the iRMX 86 BASIC I/O SYSTEM 
REFERENCE MANUAL for further information about these special 
functions. 

• All Intel-supplied file drivers. 

• Device granularities of 128, 256, 512, and 1024 bytes. 

• Up to 12 disks per controller. 

The iSBC 215/iSBX 218/iSBC 220 controller assumes that units 0-3 are 
fixed disks on drives 1-4, units 4-7 are removable disks on drives 1-4, 
and 8-11 are flexible diskette drives 1-4 (when the iSBX 218 board is 
used in conjunction with the iSBC 215 board). The driver checks only the 
four least-significant bits of the unit number. The upper bits can be 
used to identify multiple units on the same disk, as described in this 
section. 
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You must specify the following values in the device information table, in 
order to support the iSBC 215/iSBX 218/ iSBC 220 driver. 



RADEV_DEV_INFO Field 

level 

priority 

stackjsize 

data_size 

num_units 

device__init 

de vi ce_f ini sh 

device_start 

device_stop 

device interrupt 



Value 

Configuration option 

Configuration option 

300 

400 

12 or more 

I215INIT 

DEFAULTFINISH 

I215START 

DEFAULTSTOP 

I215INTERRUPT 



In addition, you must also append the following data the the device 
information structure: 



Type 

WORD 
WORD 
WORD 



Value 

Wakeup address offset (normally set to 0) 
Wakeup address base 
Wakeup port address 



You should set the wakeup address base and the wakeup port address to the 
values set with the switches on the iSBC 215 or iSBC 220 controller board, 



You must specify the following values in the unit information table, in 
order to support the iSBC 215/iSBX 218 driver: 



RADEV_UNIT_INFO Field 

track_size 
max retry 



Value 

~~0 
9 (recommended) 



In addition, you must append the following information, in sequence, to 
the unit information structure: 



Ty^e 

WORD 

WORD 
BYTE 

BYTE 



BYTE 



Value 

The device code (0 for the iSBC 215 device and 
2 for the iSBC 220 device) 

The number of cylinders on the iSBC 215 disk. 

The number of fixed data heads on the disk 
drive. 

The number of removable data heads on the disk 
drive. For a iSBX 218 flexible disk drive, 
you should set this to 1 or 2 to indicate 
single or double sided diskettes. This 
value should correspond to the flags field 
of the DUIB for the unit. 

The number of sectors per track. 
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Type 
BYTE 
DWORD 



Value 

The number of cylinders set aside for alternate 
tracks. 

The starting sector number of the device 
(normally 0). By using this field and the 
device size field in the DUIB, you can define 
several units on different parts of a single 
disk drive. 



iSBC 254 Controller . The iSBC 254 driver is a random access driver. It 
supports the following: 

• The functions F$READ, F$WRITE, F$SEEK, and F$ATTACH$DEVICE. 
F$DETACH$DEVICE , F$0PEN, and F$CL0SE are accepted, but the driver 
performs no operations for these functions. 

• All Intel-supplied file drivers. 

• Device granularities of 64, 128, 256, and 512 bytes, software 
selectable on a per-unit basis. 

• Two types of hardware configuration: 

Each iSBC 254 board as a complete device with one unit. 

Several iSBC 254 boards as separate units of a single 
imaginary device. 

You must place the following values in the device information table in 
order to support the iSBC 254 driver: 



RADEVJDEVJNFO Field 

level 

priority 

stack_size 

data_size 

numjunits 

device_init 

device_f inish 

device_start 

device_stop 

device interrupt 



Value 

Configuration option 

Configuration option 

512 

15 

Configuration option 

DEFAULTINIT 

DEFAULTFINISH 

I254START 

DEFAULTSTOP 

I254INTERRUPT 



You must specify the following values in the unit information table, in 
order to support the iSBC 254 driver: 



RADEV_UNIT__INF0 Field 

track_size 
max retry 



Value 

~0 
9 ( re commended ) 
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In addition, you must append the following information, in sequence, to 
the unit information structure: 

Type Value 

WORD 1 

WORD Base address of the board. 

WORD Number of device-granularity units of memory 

(64-, 128-, 256-, or 512-byte units) on the 

iSBC 254 board. 



iSBC 86/12A On Board USART . The On Board USART is a Basic I/O System 
driver interface to the Terminal Handler and the Debugger. It supports 
the functions F$READ, F$WRITE, F$ATTACH$DEV, and F$DETACH$DEV. This 
driver interfaces to the Basic I/O System at the DUIB level. It should 
only be used by the physical file driver. You must specify the following 
procedure names in the DEFINE_DUIB structure in order to support the On 
Board USART: 

DEFINE DUIB Field Procedure Name 



init_io THINITIO 

finish_io THFINISHIO 

queue_io THQUEUEIO 

cancel_io THCANCELIO 

The device and unit information pointers are ignored. Set the parameters 
device_info and unit__info to 0. 

The USART driver requires a Terminal Handler (or the Debugger's Terminal 
Handler) to be present in the application system. This Terminal Handler 
must use input and output mailbox names RQTHNORMIN and RQTHNORMOUT, 
respectively. 



Byte Bucket Driver . The Basic I/O System supports a byte bucket device 
by providing a byte bucket driver. This driver responds to F$READ, 
F$WRITE, F$OPEN, F$CL0SE, F$ATTACH$ DEVICE, and F$DETACH$ DEVICE, but 
performs no operations for these functions. It returns an exception code 
on an F$SEEK request. The physical file driver and the stream file 
driver can make use of the byte bucket device driver. 

The byte bucket device driver interfaces to the Basic I/O System at the 
DUIB level. In order to provide support for the byte bucket driver, you 
must specify the following values in the DEFINE_DUIB structure: 

DEFINE DUIB Field Procedure Name 



init__io BYTEBUCKETINITIO 

finish_io BYTEBUCKETFINISHIO 

queue_io BYTEBUCKETQUEUEIO 

cancel_io BYTEBUCKETCANCELIO 

9-37 



CONFIGURING THE BASIC I/O SYSTEM 



GENERAL DEVICE INFORMATION 

The Basic I/O System requires that several parameters and RAM-based data 
structures be generated for device configuration. In order for this to 
happen, you must include a %DEVICE_TABLES macro call in the configuration 
file. Place this call outside of all segment definitions in your Basic 
I/O System configuration module and immediately following the DEFINE_DUIB 
structures. The released configuration file contains an example macro 
call in the proper place. Modify this call to reflect your system. 

The file IDEVCF.INC contains the definition of %DEVICE_TABLES macro. 
IDEVCF.A86 contains an $INCLUDE statement for this file, which includes 
it in the assembly of the configuration file. 

The format of the macro call is as follows: 

%DEVICE_TABLES(num_duib, num_dev_unit, num_devices) 

where : 

num_duib Number of DUIBs that you have defined with the 

DEFINEJDUIB structure. 

num_dev_unit Number of device-units that you have defined. 

This number is 1 + (the largest dev_unit__number 
parameter). The dev_unit_number parameter was 
entered with the DEFINEJDUIB structure. 

numjdevices Number of devices defined. This number is 1 + 

(the largest device_number parameter). The 
device_number parameter was entered with the 
DEFINE DUIB structure. 



ASSEMBLING THE CONFIGURATION FILES, LINKING AND LOCATING THE BASIC I/O 
SYSTEM 

After you have modified ITABLE.A86 and IDEVCF.A86 to conform to your 
system requirements, you must assemble them and link and locate the Basic 
I/O System. IOS.CSD, a SUBMIT file contained on the Basic I/O System 
release diskette, can be used to perform these functions. In order to 
use this SUBMIT file, you must first prepare your diskettes and place 
them in the proper drives of your development system, as explained in the 
"Linking and Locating the Subsystems" section of Chapter 4. You should 
also examine ITABLE.A86 and IDEVCF.A86 to make sure that the $INCLUDE 
statements contain the proper disk identifiers. Then you can enter the 
following command: 

SUBMIT :fx:IOS(date, loc_adr) 

where : 

fx The appropriate disk identifier, indicating the 

drive containing IOS.CSD. 
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date The date on which you submit the file (maximum 

of nine characters). 

loc_adr The address at which to locate the Basic I/O 

System. If you want to enter this value as a 
hexadecimal number, you must include the suffix 
H. The base portion of this value is the base 
portion of the Basic I/O System's entry point. 
The offset portion of the entry point is 0. 
You must specify the entry point in the %J0B 
macro call for the Basic I/O System. 

This command assembles ITABLE.A86 and IDEVCF.A86, links them together 
with other modules containing Basic I/O System code, and locates the 
Basic I/O System at the specified address. It places the located Basic 
I/O System in file IOS on drive Fl. It also places the assembly listing, 
link map, and locate map on drive F3 in files IOS.LST, IOS.MPl, and 
I0S.MP2, respectively. 

You must specify a %J0B macro in the system configuration file for the 
Basic I/O System (refer to Chapter 4). In this macro, the entry point 
depends on the address at which you locate the Basic I/O System (CS:0). 
The data segment should be specified as (the Basic I/O System assigns 
its own data segment). 



BASIC I/O SYSTEM INITIALIZATION 

The Basic I/O System defines a public symbol in which it returns its 
initialization status. This symbol, RQ$AIOS$INIT$ERROR, is defined by 
the Basic I/O System as follows: 

DECLARE 

RQ$AIOS$INIT$ERROR STRUCTURE ( 

EXCEP$ INDEX WORD, 

EXCEP$CODE WORD) PUBLIC; 

If the Basic I/O System initializes properly, it sets itself up as an 
Operating System extension and returns a value of in the EXCEP$CODE 
field. If the Basic I/O System does not initialize properly, it sets 
these fields as follows: 

EXCEP$INDEX An index in the initialization task indicating 

where the task failed. 

EXCEP$CODE The first exception code that the 

initialization task incurred. 
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The iRMX 86 Application Loader provides the capability to load iAPX 86 
object files from disk into memory under the control of the iRMX 86 
Operating System. Application Loader configuration involves selecting 
parameters of the Application Loader that you wish to include in your 
application system and selecting the type of loading that the Application 
Loader can do. You perform these operations by modifying an 
Intel-supplied Application Loader configuration file and calling an 
Intel-supplied SUBMIT file. The configuration file, LCONFG.P86, is a 
PL/M-86 source file which is contained on the Application Loader release 
diskette. As released, this file selects default parameters. To change 
these parameters, you must modify this file, compile it, link it with the 
rest of the Application Loader modules, and locate the Application Loader 
at an absolute address. The Intel-supplied SUBMIT file, LOADER. CSD 
performs the compile, link, and locate operations, as well as selecting 
the type of Application Loader to include. This chapter describes these 
files. 



MODIFYING LC0NFG.P86 

You can select parameters that are associated with the Application Loader 
by making modifications to LCONFG.P86. Figure 10-1 lists the portion of 
the released LC0NFG.P86 that defines these parameters. 



loaderSconf iq: DO; 

DECLARE buf$size 
DECLARE rdbuf$size 



LITERALLY '1024'; /* BYTES */ 
LITERALLY '1024'; /* BYTES */ 



DECLARE lbuf$slze 
DECLARE l$rabuf$size 



WORD PUBLIC DATA(buf$SiZe + 11); 
WORD PUBLIC DATA(rdbuf$size); 



DECLARE L$DEFAULT$MEMpOOL WORD PUBLIC DA1A(50H); /* PAGES */ 
END loaderSconf iq; 

Figure 10-1. Application Loader Configuration File (LCONFG.P86) 
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In order to select parameter values, you must change the values specified 
with the LITERALLY statements in LCONFG.P86. The following paragraphs 
discuss the parameters. 

buf$size Size of an Application Loader internal buffer. 

This is the maximum allowable length of the 
iterative data block portion of a data record. 
Unless you are familiar with the formats of 
absolute data records, you should not change this 
parameter from its default of 1024. 

rdbuf$size Size of an I/O System buffer used for reading the 

object file from disk. 

l$default$mempool Default memory pool size, in 16-byte paragraphs, 

that jobs will have when created with the 
S$L0AD$I0$J0B and A$L0AD$I0$ JOB system calls. 
This value is used for both the maximum and 
minimum pool sizes. 



COMPILING LC0NFG.P86, LINKING AND LOCATING THE LOADER 

After you have made any necessary modifications to the Application Loader 
configuration file, LCONFG.P86, you must compile it and link and locate 
the Application Loader. LOADER. CSD, a SUBMIT file contained on the 
Application Loader release diskette, can be used to perform these 
functions. In order to use this SUBMIT file, you must first prepare your 
diskettes and place them in the proper drives of your development system, 
as explained in the "Linking and Locating the Subsystems" section of 
Chapter 4. Then you can enter the following command: 

SUBMIT :fx:LOADER(date, loc adr, code type, load job) 



where : 



fx The appropriate disk identifier, indicating the drive 

containing LOADER. CSD. 

date The date on which you submit the file (maximum of nine 

characters). 

loc_adr The address at which to locate the Application 
Loader. If you want to enter this value as a 
hexadecimal number, you must include the suffix H. 
The base portion of this value is the base portion of 
the Application Loader's entry point. The offset 
portion of the entry point is 0. You must specify the 
entry point in the %J0B macro call for the Application 
Loader. 
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code_type The type of code that the Application Loader can 
load. Enter one of the following values for this 
parameter: 

value type of code 

A Absolute code only. 

P Absolute and position independent code 
(PIC). 

L Absolute, PIC, and load-time locatable 
(LTL) code. 

Absolute, PIC, LTL, and overlay code. 

load__job The types of job loading that the Application Loader 
can perform. Enter one of the following values for 
this parameter: 

value type of job loading 

N No job loading (neither A$LOAD$IO$JOB 
nor S$LOAD$IO$JOB are supported). The 
Application Loader can handle absolute 
code and overlays only. 

A Asynchronous job loading. 

(S$LOAD$IO$JOB is not supported). 

S Both synchronous and asynchronous job 
loading. 



This command compiles LCONFG.P86, links it together with the rest of the 
Application Loader, and locates the Application Loader at the specified 
address. It places the located Application Loader on drive Fl in file 
LOADER. It also places the compilation listing, link map, and locate map 
on drive F3 in files LOADER. LST, LOADER. MP1, and LOADER. MP2, respectively. 

You must specify a %JOB macro in the system configuration file for the 
Application Loader (refer to Chapter 4). In this macro, the entry point 
depends on the address at which you locate the Application Loader 
(CS:0). The data segment base should be specified as (the Application 
Loader assigns its own data segment ) . 
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The Bootstrap Loader is used to load the iRMX 86 Operating System and/or 
application programs into memory from mass storage and begin execution of 
the system. The Bootstrap Loader consists of two stages, the first of 
which must reside in ROM, and the second of which resides on mass 
storage. The first stage contains a device driver (or drivers) which 
loads the second stage into memory. This chapter provides configuration 
parameters for the first stage and the drivers. The second stage is not 
configurable; it is put on mass storage automatically when the mass 
storage volume is formatted. 



FIRST STAGE CONFIGURATION 

First stage configuration consists of: 

• Selecting the features that you wish to include in the Bootstrap 
Loader. 

• Listing the characteristics of the possible devices from which 
the Bootstrap loader can read. 

You perform both of these operations by making modifications to a 
Bootstrap Loader first stage configuration file. This file, BS1.A86, is 
an assembly language source file which is contained on the Bootstrap 
Loader release diskette. As released, BS1.A86 defines an example 
configuration. Figure 11-1 lists the portion of BS1.A86 that defines the 
features and devices. To change the configuration of the Bootstrap 
Loader, you must modify this file, assemble it, and link it with the rest 
of the Bootstrap Loader object files and libraries. 
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naroe bsl 

SincludeC :f 1 :bsl ,inc) 

%console 

%manual 

%auto 

%device(fO, O f devl ceinit204, deviceread204) 
%device(fl, 1, deviceimt204, deviceread204) 
%device(f2, 2, devlceinit204, deviceread204) 
%device(fi, 3, devlceinit204, deviceread2G4) 
%device(dO, 0, deviceinit206, deviceread206) 
%device(wO, 0, devlceinit215, deviceread215) 
%device(wfO, 8, devicelni t2l5 # deviceread21t>) 
%device(wfl, 9, devicetnit2l5, devlceread21 5) 
%devlce(w£2, 10, deviceinit21b, devicereaa215) 
%devlce(w£3, 11, devlceinit21b, deviceread215) 
%device(bO f 0, devlceinit254, deviceread2b4) 
%end 



Figure 11-1. First Stage Configuration File (BS1.A86) 



The first stage configuration file consists of a series of macro calls 
which define the features and devices. These macros include: 

%CONSOLE 

%MANUAL 

%AUT0 

%DEVICE 

%END 

The file BS1. INC, which is available on the Bootstrap Loader release 
diskette, contains the definitions of all of the macros which you can 
call in the first stage configuration file. BS1.A86 contains an $INCLUDE 
statement for BS1.INC which includes it in the assembly of BS1.A86. 



%C0NS0LE MACRO 

This optional macro call indicates whether or not the user can supply, 
from the console, the name of the file to be loaded. If you include the 
%C0NS0LE call in your configuration file, the user has the option of 
entering the file name. If you omit the %C0NS0LE call, the Bootstrap 
Loader uses a default file name. The format of the %C0NS0LE call is as 
follows: 

%C0NS0LE 



11-2 



CONFIGURING THE BOOTSTRAP LOADER 



%MANUAL MACRO 

This optional macro indicates whether or not the user can supply, from 
the console, the name of the device to load from. If you include the 
%MANUAL call in your system, the user has the option of entering the name 
of the device to load from, as well as the name of the file to be 
loaded. If you omit the %MANUAL call from your system, the user cannot 
specify the device name. 

If you include the %MANUAL call in the first stage configuration file, 
the %CONSOLE and %AUTO calls are automatically included, without having 
to specify them. The format of the %MANUAL call is as follows: 

%MANUAL 



%AUTO MACRO 

This optional macro indicates whether or not the Bootstrap Loader can 
select devices automatically. If you include the %AUTO call in your 
first stage configuration file and the user does not specify a device 
name from the console, the Bootstrap Loader tries to initialize, in 
order, each of the devices specified with %DEVICE calls (described in the 
next section). It scans through the devices repeatedly until it 
successfully initializes one. When it does succeed in initializing a 
device, it uses that device from which to load. If you omit the %AUTO 
call from your first stage configuration file, the Bootstrap Loader can 
use just one device. The format of the %AUTO call is as follows: 

%AUTO 



%DEVICE MACRO 

This macro defines the possible devices from which the Bootstrap Loader 
can load. You must include at least one %DEVICE call in your first stage 
configuration file. You can include more than one if you also include 
the %MANUAL or %AUTO calls. The format of the %DEVICE call is as follows: 

%DEVICE(name, unit, device$init, device $read) 



where: 

name Name of the device from which to load, 

unit Unit number of the device. 
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device$init Address of a procedure that the Bootstrap Loader calls 
to initialize the device. Intel supplies this 
procedure for iSBC 204, iSBC 206, iSBC 215, iSBC 220, 
and iS.BC.254 devices. To use one of these procedures, 
specify one of the following values: 

device value 

iSBC 204 DEVICEINIT204 

iSBC 206 DEVICEINIT206 

iSBC 215 DEVICEINIT215 

iSBC 220 DEVICEINIT215 

iSBC 254 DEVICEINIT254 

device$read Address of a procedure that the Bootstrap Loader calls 
to read the device. Intel supplies this procedure for 
iSBC 204, iSBC 206, iSBC 215, iSBC 220, and iSBC 254 
devices. To use one of these procedure, specify one 
of the following values: 

device value 

iSBC 204 DEVICEREAD204 

iSBC 206 DEVICEREAD206 

iSBC 215 DEVICEREAD215 

iSBC 220 DEVICEREAD215 

iSBC 254 DEVICEREAD254 



%END MACRO 

This macro denotes the end of the first stage configuration file. You 
must include the %END call as the last statement of the first stage 
configuration file. The format of the %END call is as follows: 

%END 



DRIVER CONFIGURATION 

Driver configuration consists of providing the elementary device driver 
procedures that the Bootstrap Loader calls when it initializes and reads 
from the device. You can either include the routines provided with the 
Bootstrap Loader for the iSBC 204, 206, 215, 220, and 254 devices, or you 
can write your own driver procedures for other devices. 
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INTEL-SUPPLIED PROCEDURES 

Intel supplies elementary device driver procedures which can be used with 
iSBC 204, 206, 215, 220, and 254 devices. In order to include these 
procedures in your Bootstrap Loader, you can make modifications (if 
necessary) to driver configuration files contained on the Bootstrap 
Loader release diskette, assemble the files, and link them with the rest 
of the Bootstrap Loader object files and libraries. The following 
sections describe these files. 



iSBC 204 Device Driver 

The file B204.A86 is a device configuration file which places iSBC 204 
device driver procedures in the Bootstrap Loader. This file is an 
assembly language source file which is contained on the Bootstrap Loader 
release diskette. Figure 11-2 lists the portion of B204.A86 that 
includes the driver procedures. 



$include-(:f 2:t>204.inc) 
%b204(0A0H, 12P, 26) 



Figure 11-2. Driver Configuration File (B204.A86) 



B204.A86 contains two statements, an $INCLUDE statement and a %B204 macro 
call. The $INCLUDE statement includes file B204.INC in the assembly of 
B204.A86. B204.INC contains the definition of the %B204 macro and is 
available on the Bootstrap Loader release diskette. The %B204 call 
causes the configuration of the iSBC 204 driver routines. You can modify 
the %B204 call to reflect your system. The format of the %B204 call is 
as follows: 

%B204(io base, sector size, track size) 



where : 



io__base Base I/O port number which is selected on the iSBC 204 
board. 

sectorjsize Sector size of the device in bytes. 

track size Track size of the device in sectors. 
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The iSBC 204 device driver uses the following values for drive parameters 

parameter value 

step rate 25 milliseconds 

head settling time 20 milliseconds 
head load time 60 milliseconds 

These values refer to 8-inch drives. The values are sufficient for most 
flexible diskette drives. 



iSBC 206 Device Driver 

The file B206.A86 is a device configuration file which places iSBC 206 
device driver procedures in the Bootstrap Loader. This file is an 
assembly language source file which is contained on the Bootstrap Loader 
release diskette. Figure 11-3 lists the portion of B206.A86 that 
includes the driver procedures . 



Sinclude(:f2:D?06.inc) 
%b206C068H) 



Figure 11-3. Driver Configuration File (B206.A86) 



B206.A86 contains two statements, an $INCLUDE statement and a %B206 macro 
call. The $INCLUDE statement includes file B206.INC in the assembly of 
B206.A86. B206.INC contains the definition of the %B206 macro and is 
available on the Bootstrap Loader release diskette. The %B206 call 
causes the configuration of the iSBC 206 driver routines. You can modify 
the %B206 call to reflect your system. The format of the %B206 call is 
as follows: 

%B206(io base) 



where : 



io_base Base I/O port number which is selected on the iSBC 206 
board. 
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iSBC 215/220 Device Driver 

The file B215.A86 is a device configuration file which places iSBC 215 or 
iSBC 220 device driver procedures in the Bootstrap Loader. This file is 
an assembly language source file which is contained on the Bootstrap 
Loader release diskette. Figure 11-4 lists the portion of B215.A86 that 
includes the driver procedures. 



$ included :f2:b?i5.lnc) 

*b2l5(70H, 2S6, 7, , 9, 1024, 5) 



Figure 11-4. Driver Configuration File (B215.A86) 



B215.A86 contains two statements, an $INCLUDE statement and either a 
%B215 macro call or a %B220 macro call. The $INCLUDE statement includes 
file B215.INC in the assembly of B215.A86. B215.INC contains the 
definitions of the %B215 and %B220 macros and is available on the 
Bootstrap Loader release diskette. The %B215 call causes the 
configuration of the iSBC 215 driver routines. The %B220 call (with the 
same parameter values) causes the configuration of the iSBC 220 driver 
routines. You can modify either of these calls to reflect your system. 
The format of the two calls are as follows: 

%B215(wakeup, cylinders, fixed_heads, removable_heads , sectors, 
dev_gran, alternates) 

or 

%B220(wakeup, cylinders, fixed_heads, removable_heads , sectors, 
dev_gran, alternates) 

where : 

wakeup Base address of the wakeup port 

cylinders Number of cylinders on the disk drive or drives. All 
drives used by the Bootstrap Loader must have the same 
characteristics. 

fixed_heads Number of heads on fixed platters. 

removable_- Number of heads on removable platters, 
heads 
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sectors Number of sectors per track. 
dev_gran Number of bytes per sector, 
alternates Number of alternate cylinders. 



iSBC 254 Device Driver 

The file B254.A86 is a device configuration file which places iSBC 254 
device driver procedures in the Bootstrap Loader. This file is an 
assembly language source file which is contained on the Bootstrap Loader 
release diskette. Figure 11-5 lists the portion of B254.A86 that 
includes the driver procedures. 



$include( sf 2 so? 54. inc) 
%b254(040H, 64, 1, 8192) 



Figure 11-5. Driver Configuration File (B254.A86) 



B254.A86 contains two statements, an $INCLUDE statement and a %B254 macro 
call. The $INCLUDE statement includes file B254.INC in the assembly of 
B254.A86. B254.INC contains the definition of the %B254 macro and is 
available on the Bootstrap Loader release diskette. The %B254 call 
causes the configuration of the iSBC 254 driver routines. You can modify 
the %B254 call to reflect your system. The format of the %B254 call is 
as follows: 

%B254(io_base, dev_gran, num_boards, board_size) 



where: 

io__base 

devjgran 
num_boards 
board size 



Base I/O port number which is selected on the iSBC 254 
board. 

Page size, in bytes. 

Reserved field which must be set to 1. 

Size, in pages, of the iSBC 254 board. 
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USER-SUPPLIED PROCEDURES 

If you have devices other than iSBC 204, 206, 215, 220, or 254 devices 
that you want to use with the Bootstrap Loader, you must write device 
driver routines for these devices, specify the addresses of these 
routines in the first stage configuration file, assemble them, and link 
them to the rest of Bootstrap Loader object files and libraries. You 
must supply the following two procedures for each type of device that you 
wish to support: 

device initialization This procedure must determine whether the 

device is ready and then perform any 
necessary initialization. 

device read This procedure must read data from the 

device. 

The Bootstrap Loader expects each of these procedures to follow the 
PL/M-86 large model of computation, be of type FAR, and use 32-bit 
pointers. If you are coding your routines in PL/M-86, you should specify 
the ROM control in order to permit the Bootstrap Loader to function in 
ROM. The iRMX 86 LOADER REFERENCE MANUAL describes how to create these 
procedures. 

You can use any names you want for your device initialization and device 
read procedures. However, you must specify the names of the procedures 
in the %DEVICE macro call for the device, when you create the first stage 
configuration file. 



ASSEMBLING THE CONFIGURATION FILES, LINKING AND LOCATING THE BOOTSTRAP 
LOADER 

After you have made any necessary modifications to the Bootstrap Loader 
configuration files, BS1.A86, B204.A86, B206.A86, B215.A86, and B254.A86 
and have created any necessary device driver procedures, you should 
assemble these files and link and locate the Bootstrap Loader. BSl.CSD, 
a SUBMIT file contained on the Bootstrap Loader release diskette, can be 
used to perform these functions. In order to use this SUBMIT file, you 
must first prepare your diskettes and place them in the proper drives of 
your development system, as explained in "Linking and Locating the 
Subsystems" section of Chapter 4. You should also examine the 
configuration files to make sure that the $INCLUDE statements contain the 
proper disk identifiers. Then you can enter the following command: 

SUBMIT :fx:BSl(date, rom_loc_addr , ram_loc_addr) 

where : 

fx The appropriate disk identifier, indicating the drive 

containing BSl.CSD 

date The date on which you submit the file (maximum of nine 

characters). 
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rom_loc_addr The address at which to locate the first stage of the 
Bootstrap Loader (the CODE segment). This address 
specifies the location of the ROM-resident portion of 
the Bootstrap Loader. If you want to specify a 
hexi decimal value for this parameter, you must use the 
suffix H (and the prefix 0, if the value begins with a 
letter). 

ram_loc_addr The address at which to locate the STACK, DATA, and 
BOOT segments of the Bootstrap Loader. This address 
specifies location of the RAM-resident portion of the 
Bootstrap Loader. If you want to specify a 
hexidecimal value for this parameter, you must use the 
suffix H (and the prefix 0, if the value begins with a 
letter). 

If you have written and compiled your own device driver procedures, you 
should modify BS1.CSD in order to link these procedures in with the 
remainder of the Bootstrap Loader. To do this, place the names of your 
device driver object files in the LINK86 input list immediately before 
the line containing: 

:fl:bsl.lib & 



If you plan to run the Bootstrap Loader on an iAPX 86-based microcomputer 
system that does not include an iSBC 957A monitor and you wish to use the 
console for input /output (%MANUAL or %C0NS0LE calls present in the 
configuration file), you must supply procedures that read from and write 
to the console. The Bootstrap Loader release diskette includes a PL/M-86 
source file which contains procedures to do this. You can examine this 
file, BCICO.P86, modify the procedures to suit your needs, compile it, 
and link it to the rest of the Bootstrap Loader object files and 
libraries. You can also use these routines as examples if you need to 
supply console input and console output functions for any of your other 
routines. 

To include the read and write procedures as part of your Bootstrap 
Loader, you should add three lines to the BS1.CSD SUBMIT file. Add the 
first two lines immediately before the LINK86 statement, in order to 
compile the routines. These line are: 

PLM86 :fx:BCIC0.P86 LARGE ROM OPTIMIZER) & 
PRINT(:fx:BCICO.LST) DATE(%0) CODE 



Add the third line immediately following the LINK86 invocation, in order 
to link the routines in with the remainder of the Bootstrap Loader. This 
line is: 

:F1:BCIC0.0BJ, & 
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If you include this line, LINK86 will generate a warning message similar 
to: 

WARNING 25: EXTRA START ADDRESS IGNORED 

This is a normal message; it does not indicate an error condition. 

When locating the Bootstrap Loader, the location of the CODE segment 
determines which locations of ROM the Bootstrap Loader needs. The 
location of the STACK, DATA, and BOOT segments determines which locations 
of RAM the Bootstrap Loader needs. (The Bootstrap Loader reads its 
second stage into the BOOT segment during initialization.) You do not 
have to reserve memory for these RAM segments with %SAB macro calls. 

After you have located the Bootstrap Loader, you should burn the code 
segment into PROM. The second stage portion of the loader will be placed 
on disk automatically, when you use the Files Utility or the Human 
Interface to format the disk. Refer to the iRMX 86 INSTALLATION GUIDE 
for further information concerning the Files Utility and the iRMX 86 
HUMAN INTERFACE REFERENCE MANUAL for information concerning the Human 
Interface. 
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Extended I/O System configuration involves the following three operations: 

• Selecting the system calls of the Extended I/O System that you 
want to include in your application system and discarding the 
rest. 

• Selecting the logical devices that you want the Extended I/O 
System to initialize. 

• Selecting I/O jobs that you want the Extended I/O System to 
create during system initialization. 

You perform all of these operations by making modifications to the 
following files, all of which are contained on the Extended I/O System 
release diskette: 

File Purpose 

ETABLE.A86 System call configuration 

EDEVCF.A86 Logical device configuration 

EJ0BCF.A86 I/O job configuration 



Figure 12-1 illustrates the structure of these files. As released, these 
files define the full complement of system calls, as well as a standard 
group of logical devices and jobs. To eliminate system calls from your 
Extended I/O System, or make changes to the logical device or job 
configuration, you must make changes to these files, assemble them, link 
them to the rest of the Extended I/O System object files and libraries, 
and locate the Extended I/O System at an absolute address. The remainder 
of this chapter describes these processes. 
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SINCLUDE STATEMENT 


















SYSTEM CALL SELECTION 






EXTENDED I/O SYSTEM 

CONFIGURATION FILE 

(ETABLE.A86) 














END STATEMENT 











$INCLUDE STATEMENT 
















LOGICAL DEVICE 
SELECTION 










EXTENDED I/O SYSTEM 

CONFIGURATION FILE 

(EDEVCF.A86) 


% END_DEV_CONFIG MACRO 
















END STATEMENT 











$INCLUDE STATEMENT 
















% IO-USER MACROS 








% lO^lOB MACROS 




EXTENDED I/O SYSTEM 

CONFIGURATION FILE 

(EJOBCF.A86) 






% END_IO^JOB_CONFIG 
MACRO 












END STATEMENT 











Figure 12-1. Structure of Extended* I/O System Configuration Files 
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SELECTING SYSTEM CALLS (ETABLE.A86) 

ETABLE.A86 consists of a series of macro calls which correspond in name 
to the system calls of the Extended I/O System, Each macro gives 
directions to the assembler to include code for that system call in the 
Extended I/O System. To exclude a system call from your Extended I/O 
System, delete the metacharacter (%) of the associated macro call, and 
replace it with the comment character (;). By doing this, you change the 
macro call into a comment and prevent the assembler from evaluating it. 

The file ETABLE.MAC, which is available on the Extended I/O System 
release diskette, contains the definitions of all macros called in 
ETABLE.A86. ETABLE.A86 contains an $INCLUDE statement for ETABLE.MAC, 
which includes it in the assembly of ETABLE.A86. 

Figure 12-2 lists the released ETABLE.A86 file. If you do not modify 
this file, it will include the full complement of Extended I/O System 
system calls in your application system. 



name stable 
$inci.ud£c:f2:etablf'.mac) 

job interface 

%rocreatfiojob 
%rqexitio0ob 

configuration interface 



%kologtcalattachdevice 
%*qlogicaldetachdevice 



SYNCHRONOUS INTERFACE 



%KQSCREAT£FILE 

%RQSAITACHFILE 

%RQ5D£LETEC0NNECTI0N 

%RGSLUOKUPCUNNECTION 

%RQSCATALOC,CONNECTION 

SrRGSUrtCATALOGCONNLCTION 

%RO$CRFATEDIRECTORY 

%ROSDELETEFiLE 



Figure 12-2. System Configuration File (ETABLE.A86) 
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%RQSRENAM£FILfc; 

%RQSCH*N<;£ACCESS 

*ROSOPSN 

%kosclose 

%rosreadmqve 

%rqswritf:move 

%rqssef;k 

%rqstruncatefile 

%r0sgetfilk3tatus 

%rgsgetconnectionstatus 

%rqsspf:ctal 

END 



Figure 12-2. System Call Configuration File (ETABLE.A86) (continued) 



SELECTING LOGICAL DEVICES (EDEVCF.A86) 

EDEVCF.A86 consists of a series of macro calls that associate logical 
names with physical device-units. When the Extended I/O System is 
initialized, it creates Logical Device Objects for the devices and 
catalogs these objects in the root job's object directory under the 
specified logical names. The first time these logical names are used as 
the prefix portions of path names, the Extended I/O System creates device 
connections. 

One of the macros called in EDEVCF.A86 is the %DEV_INFO_BLOCK macro. The 
format of a call to this macro is very similar to the format of the 
LOGICAL$ATTACH$DEVICE system call (described in the iRMX 86 SYSTEM 
PROGRAMMER'S REFERENCE MANUAL). The format is as follows: 

%DEV_INFO_BLOCK('log_name', 'dev_name', file_driver) 

where: 

log_name Logical name under which the device -unit is to be 

cataloged in the root object directory. This name can 
consist of one to twelve characters. You must enclose 
this name in single quotes. 

dev_name Name of the device-unit to be assigned a logical 

name. Use the name associated with the DUIB of this 
device-unit for this parameter. (DUIBs are described 
in the "Device-Unit Information Block" section of 
Chapter 9.) You must enclose this parameter in single 
quotes. 
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file_driver Type of files which can reside on this device. 
Possible values include: 

PHYSICAL 

STREAM 

NAMED 

The other macro called in EDEVCF.A86 is the %END_DEV_CONFIG macro. The 
format of this macro is: 

%END_DEV_CONFIG(buf f er_size ) 

where : 

buffer_size Suggested size of the buffers that the Extended I/O 

System uses when it transfers information to and from 
files. The actual buffer size is the largest multiple 
of the device granularity that does not exceed the 
bufferjsize value. The device granularity is a Basic 
I/O System configuration parameter (refer to Chapter 
9). 

A call to this macro specifies the buffer size and designates the end of 
the logical device configuration • 

The file EDEVCF.MAC, which is available on the Extended I/O System 
release diskette, contains the definitions of the macros called in 
EDEVCF.A86. EDEVCF.A86 contains an $INCLUDE statement for EDEVCF.MAC, 
which includes it in the assembly of EDEVCF.A86. 

Figure 12-3 lists EDEVCF.A86 as it is released with the Extended I/O 
System. This file contains %DEV_INFO_BLOCK macro calls for several 
commonly used device-units. You should modify this file to reflect your 
hardware environment. 



NAME FDEVCF 

CGROUP GROUP CODE 

ASSUME CS : CGROUP 

$ INCLUDE CF2: EDEVCF.MAC) 



BYTF-BUCKFT 

%DEV„.INF0_3LQCK('BB', 'BB' , PHYvSlCAT*) 



Figure 12-3. Logical Device Configuration File (EDEVCF.A86) 
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TERMINAL 

%D£V.INFO_bLOCK('T0 > ,'T0', PHYSICAL) 
SHUGART 204, UNIT 0, DRIVE 

%DEV_TNFQ_SLOCK('EO', 'FO', NAMED) 
SHUG.ART 204, UNIT 1, DRIVE 1 

%DLV.INF0_8LGCK('F1', 'Ft', NAMED) 
218 WINCHESTER FLOPPY SS/SD, UNIT 0, DRIVE 

%DE V.I NFU-BL0CK( # WF0 # , # WF0' # NAMED) 
218 WINCHESTER FLOPPY SS/SD, UNIT I, DRIVE 1 

%DEV..INFG_bLOCK('WF1 ', 'WF1 ', NAMED) 
STREAM 

%DEV_INFQ«6LQCK( 'STREAM', 'STREAM', STREAM) 

%END_DEV_CONFIG(1024) 
END 



Figure 12-3. Logical Device Configuration File (EDEVCF.A86) (continued) 



SELECTING I/O JOBS (EJOBCF.A86) 

EJOBCF.A86 consists of a series of macro calls that direct the Extended 
I/O System to create I/O jobs at system initialization time. The I/O 
jobs created become children of the Extended I/O System initialization 
job. The macros called in EJOBCF.A86 are: 

%I0_USER 

%IO_JOB 

%END 10 JOB CONFIG 
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The file EJOBCF.MAC, which is available on the Extended I/O System 
release diskette, contains the definitions of all macros called in 
EJOBCF.A86. EJOBCF.A86 contains an $INCLUDE statement for EJOBCF.MAC, 
which includes it in the assembly of ETABLE.A86. Figure 12-4 lists 
EJOBCF.A86 as released with the Extended I/O System. This file contains 
macro calls for one typical job. You must modify this file to reflect 
the needs of your application system. 

If you want to include the Human Interface in your configured system, you 
must modify EJ0B.A86 to specify the Human Interface as an I/O job. Refer 
to Chapter 13 for further information. 



AM£ FjnaCfr 

GROUP GROUP CODE 

ASSUMfc CS : CGROUP 

I NCLUDECF2: EJOBCF.MAC) 

USER 'WOKLD' DEFINITION 

%IO_USER( 'WORLD', OFFFFH) 
ETOS TEST JOB 

%TO_JObC'TO','wOHT,0', 260H,0FFFFH,0 : 0,0, 0,1 b5, IB 00: 0,1 A00, 0;0 ,1200,0) 

%FND.IO.JOB«COnFIG(40) 

FND 

Figure 12-4. I/O Job Configuration File (EJ0BCF.A86) 



%I0_USER MACRO 

The %IO__USER macro defines users that are later specified in the %IO_JOB 
calls. You must define each user with %I0_USER before you refer to it, 
and you must include one %I0_USER macro for each object that you define. 
The format of the call to %I0_USER is as follows: 

%IO_USER( , user_name', user_id) 

where : 

user_name Name of the user. This name must be enclosed in 
single quotes. 

12-7 



user id 



CONFIGURING THE EXTENDED I/O SYSTEM 



A 16-bit value that specifies the id of of the user . 



Your EJOBCF.A86 file must contain at least one %IO_USER call which 
defines a user whose name is WORLD and whose id is OFFFFH. The released 
version of EJ0BCF.A86 contains such a call. 



%IO_JOB MACRO 

The %IO__JOB macro defines the I/O jobs to be created. You must include 
one macro call for each I/O job that you want the Extended I/O System to 
create. The format of the call to the %IO_JOB macro is very similar to 
the format of the CREATE$IO$JOB system call. A short description of the 
%IO_JOB parameters is included in this section, but for a complete 
description refer to the description of the CREATE$IO$JOB system call in 
the iRMX 86 EXTENDED I/O SYSTEM REFERENCE MANUAL. The format of the call 
to %IO_JOB is as follows: 

%IO_JOB ( ' def ault_pref ix ' , ' def ault__user ' , pool_min, pool_max, 
excep_handler_addr , excep_mode, job_flags, task_prior, 
task_start_addr, data_segment , stack_addr, stack_size, 
task_flags) 



where : 

default prefix 



default user 



pool min 



pool max 



excep_handler 
addr 



Logical name specifying the default prefix for 
the job. If you omit this parameter, the default 
prefix for the Extended I/O System's 
initialization job is used. This parameter must 
be enclosed in single quotes. 

Name of the default user for this job. You must 
have previously defined this user name with a 
call to %IO_USER. This parameter must be 
enclosed in single quotes. 

Minimum allowable size of the new job's memory 
pool, in 16-byte paragraphs. The Extended I/O 
System uses this parameter as the initial size of 
the memory pool for the new job. 

Maximum allowable size of the new job's memory 
pool, in 16-byte paragraphs. 

Hexadecimal pointer to the new job's default 
exception handler, in the form base: offset. A 
value of 0:0 indicates that the job uses the 
Extended I/O System exception handler. (The 
Extended I/O System exception handler is declared 
at system configuration time in the %J0B macro. 
Refer to the "%J0B Macro" section of Chapter 4 
for further information.) 
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excep mode 



Encoded value which tells the Extended I/O System 
when to pass control to the exception handler. 
Encode this value as follows: 



job flags 



Value Control Passes to Exception Handler 

Never 

1 On programmer errors only 

2 On environmental conditions only 

3 On all exceptional conditions 

Information that tells the Nucleus whether to 
validate objects used as parameters in system 
calls. Bits in this word are interpreted as 
follows: 



bit Meaning 

15-2 Reserved. 

1 If set to 0, the Nucleus validates 
objects used as parameters. If 
set to 1, the Nucleus performs no 
validation. 







Reserved. 



taskjprior 



task start addr 



Priority of the initial task in the newly created 
job. Specify a value in the range to 255 
decimal. A value of zero for this parameter 
indicates that the initial task has a priority 
equal to the maximum priority of initial job of 
the Extended I/O System. 

Hexadecimal pointer to the first instruction of 
the new job's initial task, in the form 
base: offset. 



data segment 



stack addr 



stack size 



Value to which the initial task's DS and ES 
registers are initialized. A value of zero 
indicates that the initial task assigns the data 
segment. 

Hexadecimal pointer (in the form base: offset) of 
the stack for the initial task. A value of 0:0 
causes the Nucleus to allocate a stack to the 
task and initialize the SS register to the base 
address of this segment and the SP register to 
the value of the stack_size parameter. It is 
recommended that you specify 0:0 for this 
parameter. This permits dynamic stack allocation. 

Size in bytes of the stack for the initial task. 
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task_flags A Word that specifies whether the new job's 

initial task contains floating-point 
instructions. The bits (where bit 15 is the 
high-order bit) have the following meanings: 

bit meaning 

15-1 Reserved. 

If set to 1, the initial task uses 
floating-point instructions. 
These instructions require the 
8087 NDP for execution. If set to 
0, the initial task does not 
contain floating-point 
instructions. 



%END_I0_J0B_C0NFIG MACRO 

The %END_I0_J0B_C0NFIG macro indicates the end of I/O job configuration. 
You should place this macro call at the end of EJOBCF.A86. The format of 
the call to this macro is as follows: 

%END_I0_J0B_C0NF IG ( dirjsi ze ) 

where : 

di'rjsize Maximum allowable number of entries in the directories 
of I/O jobs. A value of zero indicates that no 
directories are to be created for I/O jobs. 



ASSEMBLING THE CONFIGURATION FILES, LINKING AND LOCATING THE EXTENDED I/O 
SYSTEM 

After you have made any necessary modifications to the Extended I/O 
System configuration files, ETABLE.A86, EDEVCF.A86, and EJ0BCF.A86, you 
must assemble them and link and locate the Extended I/O System. 
EIOS.CSD, a SUBMIT file contained on the Extended I/O System release 
diskette, can be used to perform these functions. In order to use this 
SUBMIT file, you must prepare your diskettes and place them in the proper 
drives as explained in the "Linking and Locating the Subsystems" section 
of Chapter 4. You should also examine ETABLE.A86, EDEVCF.A86, and 
EJOBCF.A86 to make sure that the $INCLUDE statements contain the proper 
disk identifiers. You can then enter the following command: 

SUBMIT :fx:EI0S( date, loc_adr) 

where : 

fx The appropriate disk identifier, indicating the drive 

containing EIOS.CSD. 
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date The date on which you submit the file (maximum of nine 

characters). 

loc_adr The address at which to locate the Extended I/O 
System, If you want to enter this value as a 
hexadecimal number, you must include the suffix H. 
The base portion of this value is the base portion of 
the Extended I/O System's entry point. The offset 
portion of the entry point is 0. You must specify the 
entry point in the %J0B macro call for the Extended 
I/O System. 

This command assembles ETABLE.A86, EDEVCF.A86, and EJOBCF.A86, links them 
together with the other modules of the Extended I/O System, and locates 
the Extended I/O System at the specified address. It places the located 
Extended I/O System in file EIOS on drive Fl. It also places the 
assembly listing, link map, and locate map on drive F3 in files EIOS.LST, 
EI0S.MP1, and EI0S.MP2, respectively. 

You must specify a %J0B macro in the system configuration file for the 
Extended I/O System (refer to Chapter 4). In this macro, the entry point 
depends on the address at which you locate the Extended I/O System 
(CS:0). The data segment should be specified as (the Extended I/O 
System assigns its own data segment). 



EXTENDED I/O SYSTEM INITIALIZATION 

The Extended I/O System defines a public symbol, RQ$EIOS$INIT$ERROR, in 
which it returns its initialization status. If the Extended I/O System 
initializes properly, it attaches all logical devices specified in the 
configuration file (EDEVCF.A86) , sets itself up as an operating system 
extension, and sets RQ$EIOS$INIT$ERROR to zero. If the Extended I/O 
System does not initialize correctly, it sets RQ$EIOS$INIT$ERROR to a 
nonzero value. 

Once the initialization is complete, users can create and attach files on 
the devices specified in EDEVCF.A86 (unless they are off-line, in which 
case an exceptional condition code is returned). If one of these devices 
is switched from on-line to off-line, the Extended I/O System 
automatically marks all synchronous connections to that device as invalid 
(returns the E$BAD$ SYNC $ CONN condition code) and detaches the device. 
When the unit is switched back on, the Extended I/O System automatically 
attaches it the first time a user tries to create or attach a file on 
it. The Extended I/O System performs this service only for all devices 
that it attaches. 
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Human Interface configuration involves the following operations: 

• Designating prefixes and subpaths for the logical names required 
by the Human Interface 

• Specifying the Human Interface sign-on 

• Specifying the maximum number of characters in a command name 

• Specifying the list of directories that the Human Interface 
searches when it tries to load a command. 

You perform these operations by making modifications to an Intel-supplied 
Human Interface configuration file. This file, HCONFG.A86, is a PL/M-86 
source file which is contained on the Human Interface release diskette. 
As released, HC0NFG.A86 defines a default Human Interface. To make 
changes, you must modify HC0NFG.A86, compile it, link it with the rest of 
the Human Interface object files and libraries, and locate the Human 
Interface at an absolute address. The following sections describe this 
configuration process. 



MODIFYING HC0NFG.A86 

HC0NFG.A86 consists of a series of PL/M-86 DECLARE statements which 
identify the characteristics of the Human Interface. Figure 13-1 lists 
the portion of the released HC0NFG.A86 that you can modify. To change 
the configuration information, you must modify the values associated with 
the variables in the DECLARE statements. The following paragraphs list 
the variables you can change. 
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HCONPG: DO; 



/* path names tnat will represent default directories */ 



DECLARE 

H$system$d5rectory(*) BYTE PUBLIC DATA( 10, ' :FG:SYSTEM' ) , /* :SYSTE* 

H$prog$directoryf*) byte PUBLIC DATA(b , ' :FO:prog' ) , /* :PROG: 

H$defauit$dir(*) byte PUBLIC data(4, ' :F0: ') , /* :$: */ 



H$work$directory(*) 



BYTE PUdLIC DATA ( 8 , ' : FO : WORK * ) ? 



/* :WORK; 



DECLARE 

H$Siqn$on(*) R*TE PUBLIC DATA ( 1 5 , 'iR^X B6 HI Vl.O'), 

H$comniand$namestnax WORD PUBLIC DATAC50), /* command name max size 

HSoref ixesC*) BYTE PUBLIC DATAC2, /* number of prefixes */' 
6,':prog:', /* first prefix */ 
8,*:Stf-STEM:'); /* second prefix */ 



Figure 13-1. Human Interface Configuration File (HCONFG.P86) 



The first four variables define paths for which the Human Interface 
assigns logical names. These paths are specified in the form of 
STRINGs. The first portion of each string (the length) is a number which 
equals the number of characters in the second portion of the string. The 
second portion of the string consists of the prefix and subpath. 
Maintain this format when modifying the variables. If you specify a 
for the length of any string, the Human Interface will not create the 
corresponding logical name. 



H$ SYSTEM$DIRECTORY ( * ) 



H$PROG$DIRECTORY ( * ) 



H$DEFAULT$DIR(*) 



A BYTE array containing a STRING which 
defines the prefix and subpath of a 
directory that the Human Interface 
associates with logical name : SYSTEM:. 

A BYTE array containing a STRING which 
defines the prefix and subpath of a 
directory that the Human Interface 
associates with logical name :PROG:. 

A BYTE array containing a STRING which 
defines the prefix that the Human Interface 
associates with logical name :$:. 
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H$WORK$DIRECTORY(*) A BYTE array containing a STRING which 

defines the prefix that the Human Interface 
associates with logical name :WORK: . 

The following variable is also specified in the form of a STRING. It 
defines the Human Interface sign-on. 

H$SIGN$ON(*) A BYTE array containing a STRING which 

defines the Human Interface sign-on 
characters. These characters are displayed 
on the user terminal when the Human 
Interface begins running. 

The next variable defines the number of characters in a command name. 

H$COMMAND$NAME$MAX A WORD specifying the maximum number of 

characters in a command name. This includes 
the prefix and subpath portions of the 
command name. 

The following variable defines directories that the Human Interface 
searches when looking for a user-specified file. These directories are 
specified in the form of a STRING table. A STRING table is a BYTE array 
whose first byte specifies the number of strings in the table. The 
remaining bytes of the STRING table specify the actual STRINGs. 

H$PREFIXES(*) A BYTE array, in the form of a STRING table, 

indicating the directories that the Human 
Interface searches, in order, when looking 
for user-specified files. As many as 255 
directories can be specified in this STRING 
table. The STRINGs can contain either 
logical names (for existing files) or 
pathnames. When the Human Interface user 
specifies a pathname that does not begin 
with ($) or (:), the Human Interface appends 
the pathname from the command line to the 
end of the first directory name in the 
STRING table and searches the resulting path 
for the file. If the file is not found, the 
Human Interface repeats the process for the 
remaining directories. 

If a directory name in the STRING table 
includes a pathname (that is, it is more 
than just a logical name), it must include 
the (/) as the last character. The (/) is 
needed because the Human Interface appends 
the user-specified file name directly to the 
end of the directory name. 



13-3 



CONFIGURING THE HUMAN INTERFACE 



HCONFG.A86 also contains definitions of variables that are not described 
in this manual. These variables are defined in the configuration file to 
allow for future expansion of the configuration options. They are not 
currently user selectable. Do not modify the value of any variable that 
is not described in this section. 



COMPILING HC0NFG.A86, LINKING AND LOCATING THE HUMAN INTERFACE 

HI.CSD, a SUBMIT file contained on the Human Interface release diskette, 
can be used to link and locate the Human Interface. In order to use this 
SUBMIT file, you must first prepare your diskettes and place them in the 
proper drives of your development system, as explained in the "Linking 
and Locating the Subsystems" section of Chapter 4. Then you can enter 
the following command: 

SUBMIT :fx:HI( date, loc_adr) 

where: 

fx The appropriate disk identifier, indicating the drive 

containing HI.CSD. 

date The date on which you submit the file (maximum of nine 

characters). 

loc_adr The address at which to locate the Human Interface. 
If you want to enter this value as a hexadecimal 
number, you must include the suffix H. The base 
portion of this value is the base portion of the 
Extended I/O System* s entry point. The offset portion 
of the entry point is 0. You must specify the entry 
point in the %I0_J0B macro call for the Human 
Interface. You specify this macro call during 
Extended I/O System configuration. 

This command compiles HCONFG.P86, links together the modules that make up 
the Human Interface, and locates the Human Interface at the specified 
address. It places the located Human Interface in file HI on drive Fl. 
It also places the link and locate maps on drive F3 in files HI.MP1 and 
HI.MP2 respectively. 

Unlike the other iRMX 86 subsystems, the Human Interface does not require 
a %J0B macro in the system configuration file. Instead, the Extended I/O 
System must create the Human Interface as an I/O job. To ensure that 
this process takes place, you must include an %I0_J0B macro for the Human 
Interface in the Extended I/O System configuration file (EJOBCF.A86). 
Refer to Chapter 12 for more information about the %I0_J0B macro. In 
this %I0_J0B macro, the entry point depends on the address at which you 
locate the Human Interface (CS:0). The data segment base should be 
specified as (the Human Interface initializes its own data segment). 
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HUMAN INTERFACE REQUIREMENTS 

In order to run the Human Interface, you must include the following iRMX 
86 subsystems in your application system. 

Nucleus 

Debugger or Terminal Handler 

Basic I/O System 

Extended I/O System 

Application Loader 

Human Interface 

The Nucleus, Basic and Extended I/O Systems, and the Application Loader 
must be configured with the system calls required by the Human 
Interface. Appendix C lists these requirements. The following sections 
outline any additional requirements of the subsystems. 



TERMINAL HANDLER OR DEBUGGER REQUIREMENTS 

The Human Interface communicates to the terminal via the Basic I/O 
System, which in turn uses the Terminal Handler (or the Debugger's 
Terminal Handler). In order for this to happen, the Basic I/O System 
requires that a Terminal Handler with input and output mailbox names 
RQTHNORMIN and RQTHNORMOUT, respectively, be present in the application 
system. These mailbox names are configuration options of the Terminal 
Handler. Refer to Chapter 7 for further information. The Basic I/O 
System is unable to communicate through a Terminal Handler with different 
input and output mailbox names. 

The Human Interface library, HI. LIB, contains a module that implements 
control-C semantics. To use this module, you must link it to the 
Debugger or the Terminal Handler, depending on which you use with the 
Human Interface. To link this module, modify the Terminal Handler or 
Debugger SUBMIT file (MTH.CSD or DB.CSD) to include the following line: 

:fx:HI.LIB(HCONTC), & 

Place this line in the LINK86 input list in the place designated for the 
control-C semantics file, as indicated in Chapters 7 and 8. 



BASIC I/O SYSTEM REQUIREMENTS 

The Human Interface uses the Basic I/O System to perform I/O to secondary 
storage devices. In order to run the Human Interface, the Basic I/O 
System must contain the following file drivers: 

physical 

stream 

named 
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Ensure that these file drivers are selected in the Basic I/O System 
configuration file (ITABLE.A86) . Refer to Chapter 9 for information. 

The Basic I/O System must also contain DUIBs for the devices used by the 
Human Interface. In particular, the IDEVCF.A86 configuration file must 
contain DUIBs for devices with the following device names: 

TO Terminal device 
BB Byte bucket device 
STREAM Stream file device 

The released version of IDEVCF.A86 contains DUIBs for these devices. You 
must ensure that IDEVCF.A86 contains DUIBs for any other devices used by 
the Human Interface, such as disk drives. 

The Basic I/O System must also contain device drivers for each of the 
devices used by the Human Interface. In particular, you must ensure that 
IDEVCF.A86 includes the On Board USART driver to enable the I/O System to 
communicate with the terminal via the Terminal Handler (or the Debugger's 
Terminal Handler). 



EXTENDED I/O SYSTEM REQUIREMENTS 

The TO, BB, and STREAM devices must be logically attached when the Human 
Interface starts processing. Therefore, the Extended I/O System 
configuration file (EDEVCF.A86) must contain %DEV_INFO_BLOCK macro calls 
for each of these devices. The macro calls should assign the logical 
names to be the same as the device names. As released, EDEVCF.A86 
contains macro calls for these devices. Refer to Chapter 12 for further 
information. 

The Extended I/O System must create the Human Interface as an I/O job. 

Thus EJOBCF.A86 must contain an %IO_JOB macro call for the Human 

Interface. The default prefix for the Human Interface job is the logical 

name of the Human Interface's terminal (TO). As released, EJOBCF.A86 
contains a macro call for the Human Interface job. 

When specifying the %JOB macro for the Extended I/O System, you must 
ensure that its memory pool is large enough to include the Human 
Interface. To do this, you can specify a value of OFFFFH for the 
pool__max parameter (refer to Chapter 4 for more information about the 
%JOB macro). You should also specify a value of OFFFFH for the pool_max 
parameter in the Human Interface's %IO_JOB macro call. However, if you 
specify OFFFFH for the Extended I/O System and the Human Interface, it is 
recommended that you specify equal pool_min and pool_max values in all 
other % JOB and %IO_JOB calls to prevent these other jobs from borrowing 
memory . 
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CREATING HUMAN INTERFACE VOLUMES 

Before you can initially use the Human Interface, you must create iRMX 86 
volumes that are properly formatted and contain the Human Interface 
commands. Intel supplies one such volume in the iRMX 86 release 
package. This volume is a preconfigured flexible diskette in iRMX 86 
format (with a granularity of 128 bytes) that contains the Human 
Interface commands. You can use this diskette if your iRMX 86 system 
contains a flexible diskette drive connected to either an iSBC 204 
controller or an iSBC 215/218 controller. 

If your iRMX 86 system does not contain a flexible diskette drive, you 
must use the Files Utility to create your first Human Interface volume. 
Use the Files Utility FORMAT command to format the iRMX 86 volume and the 
Files Utility UPCOPY command to copy the Human Interface commands from 
the Human Interface release diskette to the formatted iRMX 86 volume. 
Refer to the iRMX 86 INSTALLATION GUIDE for a description of the Files 
Utility. 



CREATING HUMAN INTERFACE COMMANDS 

One of the primary functions of the Human Interface is to execute files 
of object code contained on secondary storage devices. It does this by 
loading the code into iRMX 86 memory and creating jobs for this code. 
The Human Interface is released with several such files which contain the 
Intel-supplied Human Interface commands. You can also create your own 
files of object code for the Human Interface to load as jobs. The 
procedure for creating your own commands depends on the kind of 
development system you use. 



USING A SERIES III DEVELOPMENT SYSTEM 

If you use a Series III development system to develop your commands, you 
can produce load-time locatable code (LTL), position independent code 
(PIC), or absolute code. To create LTL or PIC commands, which the Human 
Interface can load anywhere in dynamic memory, perform the following 
steps: 

1. Compile your code using the PL/M-86 compiler or assemble it using 
the 8086/8087/8088 Macro Assembler. 

2. Use LINK86 to link your code together with the necessary 
libraries and create an LTL or PIC module. Enter the LINK86 
command as follows: 
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RUN :fx:LINK86 & 

: f x : command • ob j , & 

:fx:HPIFC.LIB, & 

:fx:LPIFC.LIB, & 

:fx:EPIFC.LIB, & 

:fx: LPIFC.LIB, & 

:fx:RPIFC.LIB & 

TO :fx: command & 

PRINT(:fx: command. mpl) SYMBOLCOLUMNS ( 2 ) & 

OB JECTCONTROLS ( PURGE ) & 

PRINTCONTROLS (LINES, PUBLICS, NOCOMMENTS, SYMBOLS) & 
BIND SEGSIZE(STACK(stacksize)) MEMPOOL(minsize,maxsize) 



where : 



fx: 



command. obj 



The appropriate disk identifiers, indicating the 
drives containing the modules. 

File containing the assembled or compiled object 
code for your command. You can link in several 
files or libraries at this point, if necessary. 



HPIFC.LIB 
LPIFC.LIB 
EPIFC.LIB 
LPIFC.LIB 
RPIFC .LIB 



Interface libraries for the Human Interface, 
Application Loader, Extended I/O System, Basic I/O 
System, and Nucleus. These libraries satisfy 
external references caused by making system calls. 



command File on which LINK86 places the linked command. 
After transferring this file to an iRMX 86 
secondary storage device, you can invoke the 
command by entering its pathname. 

command. mpl File on which LINK86 places the link map. 

stacksize Size, in bytes, of the stack needed by the 

command and any system calls that the command 
makes. The Human Interface uses this value when 
it creates a job for the command. 

minsize Minimum and maximum sizes of the command^ dynamic 
maxsize memory pool, in bytes. The Human Interface uses 

these values when it creates a job for the 

command . 

The code is now ready to be transferred to an iRMX 86 secondary 
storage device. You do not need to process the code further with 
LOC86. 

3. Use the Files Utility or the Human Interface UPCOPY command to 
copy the linked command from the development system disk to an 
iRMX 86 secondary storage device. At this point you can invoke 
the command by entering its pathname at the Human Interface 
terminal. 
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You can also create your commands as absolute object modules, if you 
wish. To do this, use the output file produced by LINK86 as input to 
L0C86, and use the ADDRESSES control to specify absolute addresses for 
the code. 

There are limitations to commands containing absolute code. The next 
section discusses these limitations further. 



USING A SERIES II DEVELOPMENT SYSTEM 

If you use a Series II development system to develop your commands, you 
can produce only absolute object code which the Human Interface must load 
into one particular area of memory. To create absolute commands, perform 
the following steps: 

1. Compile your code using the PL/M-86 compiler or assemble it using 
the 8086/8087/8088 Macro Assembler. 

2. Use LINK86 to link your code together with the necessary iRMX 86 
interface libraries. Enter the LINK86 command as follows: 

:fx:LINK86 & 

: f x : command . ob j , & 

:fx:HPIFC.LIB, & 

:fx:LPIFC.LIB, & 

:fx:EPIFC.LIB, & 

:fx:IPIFC.LIB, & 

:fx:RPIFC.LIB & 

TO : f x : command . Ink PRINT ( : f x : c ommand . mp 1 ) 

where the parameters of this command mean the same as they do when 
entered with the Series III version of the LINK86 command. Notice 
that when using the Series II development system, you do not 
preface the LINK86 command with RUN and you do not use the 
SYMBOLCOLUMNS, OBJECTCONTROLS , PRINTCONTROLS , BIND, MEMPOOL, and 
SEGSIZE controls. These are not supported with the Series II 
version of LINK86. With the exception of BIND and MEMPOOL, you 
enter the omitted controls in the L0C86 command. 

3. Use LOC86 to assign absolute addresses to the linked module 
created by LINK86. Enter the L0C86 command as follows: 

:fx:LOC86 : fx : command . Ink TO :fx: command & 

ORDER (CLASSES (CODE, DATA, STACK, MEMORY)) & 

ADDRESSES (CLASSES (CODE (absolute_address))) & 

SEGSIZE (STACK (stacksize)) * & 

MAP PRINT (:fx:command.mp2) SYMBOLCOLUMNS ( 2 ) & 

OBJECTCONTROLS (PURGE) & 
PRINTCONTROLS (LINES , PUBLICS , NOCOMMENTS , SYMBOLS ) 



where : 



command. Ink Name of the link file produced previously by 
LINK86. 
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CONFIGURING THE HUMAN INTERFACE 



command Name of the file in which L0C86 writes the 

absolute module. After transferring this 
file to an iRMX 86 secondary storage device, 
you can invoke the command by entering its 
pathname . 

absolute_address Absolute starting location of the code 

segment of the command. L0C86 locates the 
remaining segments after the code segment. 
You must reserve these areas of iRMX 86 
memory during configuration with the %SAB 
macro (refer to Chapter 4). 

stacksize Size, in bytes, of the stack needed by the 
command and any system calls that the 
command makes. 

command. mp2 Name of the file in which L0C86 writes the 
locate map. 

4. Use the Files Utility or the Human Interface UPCOPY command to 
copy the located command from the development system disk to an 
iRMX 86 secondary storage device. If you have reserved the areas 
of iRMX 86 memory that the command needs with the %SAB macro 
during system configuration, you can invoke the command by 
entering its pathname at the Human Interface terminal. 



ADDITIONAL REQUIREMENTS FOR ABSOLUTE CODE 

When the commands you create contain absolute object code, you must take 
steps during the configuration process to ensure that this code loads and 
executes correctly, without affecting the remainder of the application 
system. 

Since absolute code contains the addresses at which it is to reside as 
part of the code, the Application Loader, when called by the Human 
Interface, cannot load this code at any convenient place in iRMX 86 
memory. Instead, it must load this code at the exact place specified in 
the code. If that place in iRMX 86 memory contains other objects (as it 
might if the memory is part of a dymanic memory pool), the act of loading 
the file can harm or destroy other tasks. If the place in memory 
contains part of the Operating System, the results can be worse. In 
order to ensure that no damage occurs when the Application Loader loads 
absolu te files, you mus t use the % SAB macro call to reserve areas in to 
which the Application Loader (when called by the Human Ingerface) will 
later load code (refer to Chapter 4 for a description of the %SAB 
macro). If you do this, no other objects will use the specified areas of 
memory, and the Application Loader can safely load your commands into 
that area for execution. 

If you create your commands as LTL or PIC modules on a Series III 
development system, you do not have to reserve memory with %SAB macros. 
The Application Loader loads LTL and PIC modules into convenient areas of 
dynamic memory. 
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APPENDIX A. EXAMPLE SYSTEM CONFIGURATION 



One of the iRMX 86 release diskettes contains a demonstration system. 
This system consists of the following: 

• Nucleus 

• Debugger 

• root job 

• application job consisting of a BASIC interpreter 

The system contained on the release diskette has already been 
configured. In order to run it, make sure that your hardware is 
assembled correctly and load the system into your iSBC 86/12A single 
board computer. Refer to the iRMX 86 INSTALLATION GUIDE for further 
information on using this system. This appendix, however, shows how to 
use the procedures described previously in this manual and build the 
demonstration system from its individual parts. 

In order to build the demonstration system, this appendix assumes that 
you have the following: 

• An INTELLEC Series II Microcomputer Development System with at 
least four disk drives. 

• A system disk containing ASM86, LINK86, and LOC86. 

• The Nucleus release diskette, the Debugger release diskette, the 
demonstration system release diskette, and the iSBC 957A release 
diskette. 



This appendix uses the SUBMIT files provided on the subsystem release 
diskettes and described in the previous chapters of this manual to link 
and locate the Nucleus and Debugger. The demonstration system release 
diskette contains different SUBMIT files that link and locate the 
Nucleus, Debugger, and TBASIC interpreter. These SUBMIT files do not, 
however, follow the disk drive conventions outlined in Chapter 4. They 
assume that you have only two disk drives in your development system. 
You can use the files on the demonstration system release diskette, but 
this appendix does not describe the commands used to submit them. 

This Appendix also makes assumptions about terminal characteristics, 
naming files, and placing files on diskettes. These are made for 
convenience, not out of necessity. It also assumes that you are going to 
use the iSBC 957A package to load the system into the iSBC 86/12A single 
board computer. 
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EXAMPLE SYSTEM CONFIGURATION 



PREPARE A MEMORY MAP 

The first step in the configuration process is preparing the memory map 
to describe the general layout of the system. Figure A-l contains such a 
memory map. 

There are several things to notice about this memory map. They are: 

• The highest RAM address recorded indicates that this system has 
128K of RAM. 

• The iSBC 957A package will be used to load this system into 
memory. Thus space is allocated in the memory map for the iSBC 
957A monitor. 

• Space is left for the Bootstrap Loader, should you want to add it 
to your application system at a later date. The space left in 
this example is sufficient for most configurations of the 
Bootstrap Loader. However, if you intend to bootstrap from a 
device with a 1024-byte sector size or larger, you should leave 
more room, starting your system at 200:0. 

• The modules will be located in memory as described in Chapter 4. 
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iRMX 86 w SYSTEM MEMORY MAP WORKSHEET 



Configuration file name: 

Start address/ 
Data segment base 



Module 



Length 



Absolute 
Address 



(reserved) 



reset vector 



iSBC 957A monitor 



Highest RAM address 



Application Job 



Root job 



Debugger 



Nucleus 



(space for Bootstrap Loader) 



iSBC 957A monitor data 



Interrupt vector 



< 
< 
< 
< 
< 
< 
< 
< 



< 
< 
< 
< 
< 
< 
< 
< 



< 
< 
< 
< 



FFFF : F 

FFFF : 
FEOO : 
1FFF:F 



1C0:0 

1BF:F 

6F:F 

40:0 

0:0 



Figure A-l. Preparing the Memory Map 
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CONFIGURE THE SUBSYSTEMS AND LINK AND LOCATE THE SYSTEM 

The next steps you must perform involve preparing configuration files for 
the Nucleus and the Debugger, assembling these files, and linking and 
locating all of the pieces of your system. You should fill out the 
memory map each time you locate a module, in order to keep track of the 
modules and the memory that they require. Figure A-2 shows a filled out 
memory map. The following sections refer to this figure. 
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EXAMPLE SYSTEM CONFIGURATION 



iRMX 86™ SYSTEM MEMORY MAP WORKSHEET 



Configuration file name: 

Start address/ 
Data segment base 



s> 



£)( 



•>{ 



s 



SS=11C5:0 



length=0A04 



CSTART=0E70:90 



Module 



Length 



(reserved) 



reset vector 



iSBC 957A monitor 



Highest RAM address 



Application Job 



Root job 



Debugger 



Nucleus 



(space for Bootstrap Loader) 



iSBC 957A monitor data 



Interrupt vector 



< 
< 
< 
< 
< 
< 
< 
< 



< 
< 
< 
< 
< 
< 
< 
< 



< 
< 
< 
< 



Absolute 
Address 



FFFF : F 

FFFF : 
FE00:0 
1FFF : F 
127A.-0 
0E70:0 

0E10:0 

OEOE : F 
6B2:0 

6B1:B 

1C0:0 

1BF:F 

6F:F 

40:0 

0:0 



Figure A-2. Completed Memory Map 
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EXAMPLE SYSTEM CONFIGURATION 



PREPARE, LINK, AND LOCATE THE NUCLEUS 

You should start the configuration process with the Nucleus, To do this, 
place the diskettes in the proper drives of the development system 
(system diskette in drive FO, configuration diskette in drive Fl, Nucleus 
release diskette in drive F2, and scratch and listing diskette in drive 
F3). Then copy the Nucleus configuration file, NTABLE.A86, from the 
release diskette to your configuration diskette. Modify NTABLE.A86 so 
that it includes only those features and system calls that your 
application system requires. (You do not need to modify NDEVCF.A86 if 
you are running on the iSBC 86/12A board.) Figure A-3 shows a modified 
version of this file that specifies the system calls and features needed 
by the TBASIC interpreter. 



$ INCLUDE ( 5 F2:NTABLF. MAC) 
SEJECT 



NUCLEUS FEATURE CONFIGURATION TABLE 

» 

TO LEAVE OUT A FEATURE, CHANGE THE '%' TO THE COMMENT 
CHARACTER *;' . 

*PARAMETER_VALIDATION 
%SYSTEM„.EXCEPTION_HANDLER 

SEJECT 



NUCLEUS PRIMITIVE CONFIGURATION TABLE 

TO CONFIGURE A NUCLEUS PRIMITIVE OUT OF THE IRMX 86 SYSTEM, 
PEPLACE THE '*' BY THE COMMENT CHARACTER * ; ' . CALLS TO 
PRIMITIVES NOT CONFIGURED IN THE SYSTEM WILL RESULT IN AN 
E$NOT$CQNFIGURED EXCEPTIONAL CONDITION. 



««•.•.•.•»•••*•*•••.•*•«•••*••«•••*•..• 



%RQGETT*PE 

%r0disabledeleti0n 

*roenabledeletion 

%rqcatalogobject 

%rquncaialogobjecx 

%rolookupobject 

;rqcpeateextension 

? ROUEtiETEEXTENSION 

;rqcreatecomposite 



Figure A-3. Example Nucleus Configuration File 
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END 



JRQDFLETFCOMPOSITE 
;R0IN£P£CTC0MP0SITE 
:RQALXERCOMpnsiTE 
;kOFORCEDELETE 

%rqcreatejob 

;RODELETEJOb 

JRQOFESPRING 

%RQCREATETASK 

%RQDEbETETASK 

%ROSUSPEVDTASK 

%roresumetask 

%ROSliEF!P 

%ROGETTASKTOKENS 

%ROGEXPRTORITY 

;ROSErPRTORlTY 

%R0CREATEMA1LBQX 

%RODELETEMAILBOX 

%RQSENDMESSAGE 

%R0RECEIV£MES6AGE 

%RQCREATESE^ApHORE 

%RODELEIESEMAPHORE 

fcROSEiMDUNITS 

%h0rece1vemnits 

?rocreateregiom 

;rqdeleteregiqn 

;rosendcontrol 

;roreceivecontrol 

;rqacceptcontrol 

%rocreatesegment 

%rodelexesegment 

%R0GEXSI7E 

jrogexpoolattrib 
;rosetpqolmin 

;ROSEiOSEXTENSTUM 

%r0settnterrupt 

yrqentertnterrupt 

%roenable 

%rqotsable 

jroresetinterrupt 

;rogftlevel 

*rq£xit1nterrupt 

%rtOSIGNAMNTEKRUPT 

%ROwAlTINTERRUPT 

?ROGETEXCEPlIONHAiMDLER 

;rosetexceptiunhandler 

%ROSlGNAIiEXCEPTION 



Figure A-3. Example Nucleus Configuration File (continued) 
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Next, copy the Nucleus SUBMIT file, NUCLUS.CSD from the release diskette 
on drive F2 to the configuration diskette on drve Fl. Modify the ASM86 
command in NUCLUS.CSD so that it reads the configuration file 
(NTABLE.A86) from drive Fl instead of from drive F2. Then call the 
version of NUCLUS.CSD that resides on Fl to assemble the configuration 
files and link and locate the Nucleus. From the memory map in Figure 
A-l, you can see that the Nucleus should be located at address 1C0:0. 
This allows room for the interrupt vector and the iSBC 957A monitor at 
lower addresses, and also allows you to include the Bootstrap Loader in 
your application system at a later date. Therefore, enter the following 
command: 

SUBMIT :Fl:No<JLUS(date, 1C00H) 

where date is the date on which you submit the file. NUCLUS.CSD places 
the located Nucleus in file NUCLUS on drive Fl. It places the locate map 
in file NUCLUS. MP2 on drive F3. Figure A-4 shows the important parts of 
the Nucleus locate map. 



TSIS-IT MCS-R6 LOCATFR, VI. 3 INVOKED BY: 
L0C86 & 

:£3:nuclus.ln< tq :fi:nuclus & 

MAP PRTNTCf 3:nuclus.mp2) & 

NOLINES NQCOMMENTS N0$YH80LS «- 

S£GSTZE(stack(On & 

nRDEP(classesCco<le, data)) & 

ADDRESSES(ciasses (code( 01 C00H) ) ) 
WARNING 26: DECREASING SIZE OF SEGMENT 
SEGMENT: STACK 

SYMBOL TABLE OF MODULE NBEG1N 
READ FROM FILE : E3 ; NUCLUS .LNK 
WRITTEN TO FTLF 5Fl:NuCLUi> 

BASE OFFSET TtfPE oYMROL BASE OFFSET TYPE SYMBOL 

01C0H OOO0H PUB NBEGIN 

MEMORY M AP OF MODULE NBEGIN 
READ FROM FILE : F3 : NUCLUS . LNK 
WRITTEN TO FTLF :F1:NUCLUS 



SEGMENT 


MAP 










START 


STOP 


LENGTH 


ALIGN 


NAME 


CLASS 


00000H 


00 3FFH 


'0400H 


A 


(ABSOLUTF) 




01C00H 


0645BH 


485CH 


W 


CODE 


CODE 


0645CH 


06475H 


001 AH 

• 
• 
• 


w 


PbJ-SEG 


CODE 



Figure A-4. Nucleus Locate Map 
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069K0H 069F3H 

0696.4H 069F4H 0000H W STACK STACK 



0004H 


G 


LIB.8/.IN1T 


OOOOH 


W 


STACK 


012CH 


G 


ISTACK 


oooo« 


W 


MLMORY 



069F0H 06B1BH 012CH G ISTACK STACK 

06B1CH 06B1CH 0000« W MEMORY MFMORY 



GROUP MAP 

ADDRESS GROUP UR S£G*FNT NAMfc, 
065S0H DGROuP 

DATA 

KFADHHSTPOOT.UATA 

KS1ACK 

DELAYMSTROOI..DATA 

inLFTASK^DATA 

ISTACK 

iNTver.RisG.siif: 

EXT.KFG-SFG 
JHB-RFG-SFG 
SFM.RFG-SFG 
MAIL„P£G_S£G 
On_REG_Sfc;G 
pOUL^P fcG.SfcG 
DFLFTION_P£G..SEG 
OICOOH CGROuP 

cnoF 

OBJ_SFG 

JOB-SFG 

TASK.ScG 

MR.SEG 

SFH.SFG 

RFG^SFG 

FS.SfcG 

INT-SFG 

• 
Figure A-4. Nucleus Locate Map (continued) 



As you can see from arrow Al in Figure A-4, the next available memory 
location is 6B1:C. The last location used by the Nucleus was 6B1:B. 
Record these values on the memory map as shown in portions A and part of 
B in Figure A-2. 



® 
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EXAMPLE SYSTEM CONFIGURATION 



PREPARE, LINK, AND LOCATE THE DEBUGGER 

You should continue the configuration process with the Debugger. This 
example assumes that you can use the released versions of the Debugger 
SUBMIT file and configuration file. Thus you do not need to copy any 
files to your configuration diskette and make modifications. Just make 
sure that you place the diskettes in the proper drives of your 
development system (system diskette in drive FO, configuration diskette 
in drive Fl, Debugger release diskette in drive F2, and scratch and 
listing diskette in drive F3). Then call the Debugger SUBMIT file, 
DB.CSD, to assemble the DTHCNF.A86 and link and locate the Debugger. 
Since you have already located the Nucleus, you know that the last memory 
location used is 6B1BH. Therefore, use a figure of 6B20H in the call to 
DB.CSD. This call appears as follows: 

SUBMIT :F2:DB(date, 6B20H) 

where date is the date on which you submit the file. DB.CSD places the 
located Debugger in file DB on drive Fl. It places the locate map in 
file DB.MP2 on drive F3. Figure A-5 shows the important parts of this 
locate map. 



TSIS-J.I MCS-.flb LOCATE, VI. 3 INVOKED BY: 
LOC86 * & 

:f3:dt).lnK TU :fl:db & 

MAP PRINTC :t3:db.ino2) & 

NOLiNES NQCQMMFNTS N05YMB0LS & 

SEGSlZE(stack(0)) & 

ORDERCclassesCcode, data)) & 

ADDRESSES (classes! code C06b2 OH)) ) 
WARNING 76: DECREASING SIZE. UF SEGMENT 
SEGMENT: ST»CK 



SYMBOL TABLE OF MODULE OBUGA 
P£AD FROM FILE :Fi:pR.LNK 
WRITTEN TO FILE :F1 :Db 

BASE OFFSET TYPE SYMBOL 

0o82H 00OOH PUB RQDBUGINIT 



BASE OFFSET TYPE SYMBOL 



MEMORY MAP OF MODULE DBUGA 
READ FROM FILE :Fj:oB.LrtK 
WRITTEN TO FTLF :F 1 :Da 



SEGMENT 


MAP 








START 


STOP 


LEWGl'H 


ALIGN NAME 


CLASS 


06B20H 
ODBFEH 


ODBFDH 
ODCOiH 


7 0DEH-. 
0006H 


W CODE 

B TH.CNF..5EG1 


CODE . 
CODE 



Figure A-5. Debugger Locate Map 
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0DC04H 0DC09U OOObH B Th.CMF.SEG2 CODE 

ODCOAH ODCUF 

0DC12H 0DC15H 

0DC16H ODC17H 

0DC18H 0DC22H 

0DC23H 0DC2EH 

ODC30H OFOEFH 

0£OFOH OEOFOH 

OEOFOH OFOFOF 

OfcOFOH OFOFQH OOOOH W MLMOP* MEMORY -« (Bl 



OOOdH 


B 


TH.CKF.SEG3 


CODE 


0004H 


B 


TH.CNF.SEG4 


CODF 


0002H 


B 


TH.CMF.SFG5 


CODE 


OOOBH 


B 


NORM.lN.MBX.St 
-G 
NURM.OUT.MBX-S 


CODE 


OOOCH 


B 


CODF 






-FG 




04CUH 


W 


DATA 


DATA 


OOOOH 


G 


??Sfc!G 




OQOO" 


W 


STACK 


STACK 


OOOOH 


w 


MLMOP* 


MEMORY 




GROUP MAP 

ADDRESS GROUP OR SEGMENT NAME 
0DC30H DGROUP 

DATA 
06B20H CGROUP 

CODF 

TH.CNF.SEGl 

IH.CNF.SEGJ 
TH.CNF.SEG4 
TH.GNF. S£G6 
NORM_TN.MBX_SFG 
NORM^OUT.MtiX. SEG 



Figure A-5. Debugger Locate Map (continued) 



Arrow Bl shows the only important piece of information in Figure A-5 that 
you should record on the memory map. It identifies the next available 
memory location, address 0E0F:0. The last location used by the Debugger 
is 0E0E:F. Record these addresses on the memory map. This is shown in 
portions B and C of Figure A-2. You need to know the next available 
address in order to leave enough space for the root job and correctly 
locate the application job. 

The entry point of the Debugger is determined from the address at which 
you locate the Debugger. The base portion of the entry point is the base 
portion of the location address (6B2). The offset portion of the entry 
point is 0. Thus the Debugger entry point is 6B2:0. You must supply 
this address later in the %JOB macro call for the Debugger. 
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EXAMPLE SYSTEM CONFIGURATION 



ALLOW SPACE FOR THE ROOT JOB 

Use the address 0E10:0 as the starting address of the root job. Record 
this value and the estimated size on the memory map. You do not know the 
exact size since you have not created the root job yet. However, for 
this system, use a size estimate of 600H bytes. Add this value to the 
starting address and record the result, 0E70:0, on the memory map. Use 
this value as the starting address of the application job. Portion C of 
Figure A-2 shows this. 



LINK THE APPLICATION JOB 

Next, use LINKS 6 to link the modules of the TBASIC interpreter job 
together. Before you do this, however, copy the file SBCIOL. LIB from the 
iSBC 957A release diskette to your configuration diskette. Also copy the 
interface library, RPIFL.LIB, from the Nucleus release diskette to your 
configuration diskette. Place the diskettes in the proper drives of the 
development system (system diskette in drive FO, configuration diskette 
in drive Fl, demonstration system release diskette in drive F2, and 
scratch and listing diskette in drive F3) , and enter the following 
command : 



LINK86 :F2: TBASIC. OB J, 
:F2:PTHI0.0BJ, 
:F2:PT0KEN.0BJ, 
:F2:PERR.0BJ, 
:F2:PINT.LIB, 
:F1: SBCIOL. LIB, 
:F1: RPIFL.LIB 
TO :F3: TBASIC. LNK MAP PRINT(:F3: TBASIC. MPl) 



The files linked in this process contain the following information: 

TBASIC. OBJ This file contains the initialization task and the 
interpreter. 



PERR.OBJ 
PTOKEN.OBJ 



This file contains error printing routines. 

This file contains a token scanner for PL/M-86 
routines. 



PTHIO.OBJ 

PINT. LIB 

SBCIOL. LIB 
RPIFL.LIB 



This file contains the interface between the 
Terminal Handler and the interpreter. 

This file contains a library of PL/M-86 routines 
that interface with the iRMX 86 Operating System. 

This file contains the iSBC 957A library. 

This file contains the interface library for 
application jobs. 



LINK86 places the linked application job in file TBASIC. LNK on drive F3. 
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LOCATE THE APPLICATION JOB 

After linking the application job, use LOC86 to assign absolute 
locations. By examining the memory map, you can see that the next 
available location is 0E70:0. Use LOC86 to locate the application job 
there. To do this, enter the following command: 

LOC86 :F3:TBASIC.LNK TO :F1:TBASIC & 

ORDER (CLASSES (CODE, DATA, STACK, MEMORY)) & 

ADDRESSES (CLASSES (CODE (OE700H))) & 

MAP PRINT ( :F3 : TBASIC. MP2) & 

OBJECTCONTROLS ( NOLINES , NOCOMMENTS , & 
NOPUBLICS , NOSYMBOLS ) 

LOC86 places the located application job in file TBASIC on drive Fl. It 
places the locate map in file TBASIC. MP2 on drive F3. Figure A-6 shows 
the important portions of the application job locate map. 



TSIS-1I 
LUC86 



MCS-96 LOCATOR, VI. 3 INVOKED BY: 



:f 3: tbasic.lnK Tu :fi:tbasic 

Order (classes (code, data, stack, triemorv )) 

addresses (classes (code (00E700H))) 

man print ( :f 3:tbasic.*p2) 

ObJECTCUNTRUr.S(NOLTNF:s,wOCO«Mt.MTS, 

Nr>3YMBuLS,M0pl!br. t iCS) 



Sy^BDli TABLE OF MODULE TBASIC 
READ FROM FILE : F3 • TBASIC . LNK 
WKTTTfcN TO FILE :F1. :TbASTC 



BASE 



OFFSET TlfPf SYMPOL 



BASE 



OFFSET TKPE SYMBOL 



OE70H 


UOCFH 


PUB 


wSTART 




OE70H 


0090H 


PUB 


CSTAHT -*-^p: 


1089H 


008BH 


PUB 


XXXBGN 




1089H 


108RH 


PUB 


IX TEND ^~ 


1099H 


0004H 


PUB 


VAgBGV 




1084H 


0051H 


PUB 


TXTUNF 


0F20H 


01F6H 


PUB 


^FXCHAR 




0F20H 


0ly9H 


PUB 


FLUShlNPUT 


0F20H 


0148H 


PUB 


PUICHAR 




0F20H 


0OF4H 


PUB 


FLUSHDUTPUT 


0F20H 


0024H 


PUB 


1NI.TTH10 




0F44H 


003DH 


PUB 


TOKFNTZE 


0F44H 


001'CH 


PUB 


HEX 




0F44H 


0004H 


PUB 


HFXCHARS 


0F86H 


005EH 


PUB 


fERRUR 


• 
• 
• 


0F8FH 


0014H 


PUB 


PCRTSEMA 








Figure A-6. 


Application 


Job Locate Map 
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EXAMPLE SYSTEM CONFIGURATION 



MEMORY MAP OF MODULE TBASIC 
READ FROM, FILE : E 3 : T*AS1C .LivK 
WRITTEN TO FILE :F1:TflASTC 

MODULE START ADDRESS PARAGRAPH = 0E70H OFFSET = OO^OH 
SEGMENT MAP 



START 

OE700H 
0F20AH 

0F444H 
0F86CH 



STOP 

OF208H 
0F443H 

0F86BH 
0F8FCH 



LENGTH ALTGN NAME 



CLASS 



0609H 


G 


CODE 


CODE 


023AH 


W 


TERMINALHANDLE 
-RIO.CODE 


CODE 


04?8H 


W 


TOKENIZE-CODE 


CODE 


0091^ 

• 
• 


w 


PERKOK_COi>F 


CODE 



11C44H 11C44H 0000H W IMTTASKS1GNAL DATA 

--DATA 

11C50H 12653H 0A04H G STACK STACK 
12660H 12660H 0000H G ??SEG 

12660H 1279EH 0l'3FH W CONST CONST 

127AOH 127AOH OOOOH W MEMQp* MEMORY 




59 

© 



GROUP MAP 

ADDRESS GROUP OP SEGtfFNT NAME 



10840H 



0E700H 



DGROUP 

CONST 

DATA 

DATA2 

STACK 

MEMORY 

CGROUP 

CODE 



Figure A-6. Application Job Locate Map (continued) 



As with the Debugger locate map, there are three pieces of important 
information in Figure A-6 which you must record on the memory map. 
Arrows Dl, D2, and D3 mark them. 

Arrow Dl shows the next available memory location, 127A:0. Record this 
value on the memory map. It will be used when when calling the %SAB 
macro to reserve memory for the application system. This is shown in 
portion D of Figure A-2. 
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EXAMPLE SYSTEM CONFIGURATION 



Arrow D2 shows the entry point of the first-level job's initialization 
task, CSTART. Record the address of CSTART, 0E70:090, on the left 
portion of the memory map, near the other information for the application 
job. This is shown in portion D of Figure A-2. You must later provide 
this information in the %JOB macro call for the application job. 

Arrow D3 shows the stack segment starting address and length. Record the 
starting address, 11C5:0, and the length, 0A04, on the left portion of 
the memory map, near the other information for the application job. This 
is shown in portion D of Figure A-2. This job has a statically allocated 
stack and so you must provide this information in the %JOB macro call. 

This application job assumes that the code segment and the data segment 
are the same. Therefore, it is not necessary to record any information 
about the data segment in the memory map. 



BUILD THE CONFIGURATION FILE 

After you have located the Nucleus, the Debugger, and the application job 
and filled out the memory map, you have enough information to build the 
configuration file needed by the root job. This involves creating a file 
containing an $INCLUDE statement, a %SYSTEM macro call, %SAB macro calls, 
%JOB macro calls and an %END macro call. The following sections show 
filled out worksheets for these macros and discuss the parameters. Then 
the actual configuration file itself is shown. 



%JOB MACRO CALLS 

For this system, you must make two %JOB calls; one for the Debugger and 
one for the application job. The order in which you include these calls 
in the configuration file is important because that is the order in which 
the jobs are initialized when the system starts running. Make the %JOB 
call for the Debugger first. 



Debugger %JOB Call 

Figure A- 7 shows the completed worksheet for the Debugger's %JOB call. 
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EXAMPLE SYSTEM CONFIGURATION 



Macro < 

Number 

CONFIG! 


call: JOB (defines first- 


•level jobs ) - for Debugger 


of calls required one for each first-level job 




JRATION FILE NAME: CONFIG. A86 




FORMAT 








- 




suggested 






parameter 


type default 


value 


%JOB 


(directory_size , 


word (0) 







pool_min, 


word 


1FFH 




pool max, 


word (OFFFFH) 


1FFH 




max objects, 


word 


OFFFFH 




max_tasks, 


word 


OFFFFH 




max job priority 


byte 







exception handler_entry 5 


addr (0:0) 


0:0 




exception handler mode, 


byte (1) 


1 




job_flags, 


word (0) 


1 




init task priority, 


byte (0) 







init_task_entry , 


addr 


6B2:0000 




data_segment__base , 


base (0) 







stack_pointer , 


addr (0:0) 


0:0 




stack size, 


word (512) 


512 




task_f lags ) 


word (0) 





NOTES : 








1. 


Type addr is specified as 


$ base: offset 




2. 


Types addr and base must 


be entered as hexadecimal numbers 




without the suffix H. Types word and byte defau. 


It to 




decimal, but will accept 


all radix suffixes. 





Figure A-7. Completed Debugger %J0B Macro Worksheet 
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EXAMPLE SYSTEM CONFIGURATION 



The parameters are described in the following: 



directory_size 

through 

max_tasks 

max job priority 



exception_handler_- 
entry 



The first five parameters affect the Debugger 
while it is running. Enter these parameters 
as shown in Figure A-7. 

The indicates that the priority of the root 
job is the maximum priority for tasks in this 
job. 

The 0:0 value means that the default system 
exception handler identified in the %SYSTEM 
call is used. 



exception_handler_mode The 1 indicates that the exception handler is 

called in the event of programming errors. 



job_flags 

init_task_priority 
ini t_t ask_en t ry 

data_segment_base 

stack_pointer 

stack_size 
task_flags 



The indicates that the Nucleus does not 
validate parameters. 

This value was listed in Table 4-1. 

This value depends on the address specified 
when locating the Debugger. It is always 
(base of the location address) :0. 

The indicates that the Debugger assigns its 
own data segment. 

The 0:0 indicates that the Nucleus allocates 
the stack segment. 

This value was listed in Table 4-1. 

The indicates that the Debugger does not 
use the 8087 NDP component. 



Application Job %J0B Call 

Figure A-8 shows the completed %J0B macro worksheet for the application 
job. 
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EXAMPLE SYSTEM CONFIGURATION 



Macro < 

Number 

CONFIGl 


:all: JOB (defines first-level 


jobs) - for TBASIC 


of calls required: 


one for each 


first-level job 


JRATION FILE NAME: 


CONFIG. A86 








FORMAT: 








suggested 






parameter 


type 




default 


value 


%JOB 


(directory size, 


word 




(0) 


20 




pooljmin, 


word 






1FFH 




pool_max, 


word 




(OFFFFH) 


OFFFFH 




max_objects, 


word 






OFFFFH 




max_tasks, 


word 






OFFFFH 




max_job_priority, 


byte 











exception_handler entry, addr 




(0:0) 


0:0 




exception handler mode, byte 




(1) 


1 




job_flags, 


word 




(0) 


1 




init task priority, 


byte 




(0) 


131 




init task entry, 


addr 






0E70:090 




data segment base, 


base 




(0) 







stack_pointer , 


addr 




(0:0) 


11C5.-0 




stack_size, 


word 




(512) 


0A04H 




task flags) 


word 




(0) 





NOTES: 












1. 


Type addr is specified as base: offset 






2. 


Types addr and base 


must be specified 


as hexadecimal numbers 




without the suffix H. Types word 


and 


byte default to decimal 




but will accept all 


radix suffixes. 







Figure A-8. Completed Application Job %J0B Macro Worksheet 
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EXAMPLE SYSTEM CONFIGURATION 



The values shown in Figure A-8 are very similar to those shown in Figure 
A-7. The major differences are outlined as follows: 



init_task_priority 

init_task_entry 
data_segment_base 

stack_pointer 

stack size 



A value of 131 is the recommended value for 
this job. 

This value was taken from the memory map. 

This indicates that the task assigns the data 
segment. 

This job has a statically allocated stack. 
This value was taken from the memory map. 

This value was taken from the memory map. 



%SAB MACRO CALLS 

This system uses two %SAB calls, one for the memory needed by the Nucleus 
and the first-level jobs, and the other for the remainder of the address 
space over 128K. Figure A-9 contains the completed worksheet for the two 
%SAB calls. 
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EXAMPLE SYSTEM CONFIGURATION 



Macro call: 



SAB (for system address blocks) 



Number of calls required: 
CONFIGURATION FILE NAME: 



one or more 



FORMAT: 



parameter 



%SAB (start_base, 
end_base, 
type) 



type 


suggested 
default 


value 


base 
base 





127 A 


see note 
1 


U 


U 



%SAB (startjbase, 
end_base, 
type) 



base 
base 

see note 
1 



U 



2000 

FFFF 

U 



%SAB (start_base, 
end_base, 
type) 



base 
base 

see note 
1 



U 



NOTES: 



1. The type parameter is reserved for future use. Enter the 
character U for this parameter, 

2. A SAB is declared between start_base:0 and end_base:F, 
inclusive. 

3. Types addr and base must be entered as hexadecimal numbers 
without the suffix H. Types word andrbyte default to decimal 
but will accept all radix suffixes. 



Figure A-9. Completed %SAB Macro Worksheet 
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EXAMPLE SYSTEM CONFIGURATION 



The first %SAB call shown in Figure A-9 reserves the memory needed for 
the entire application system. The end_base parameter is taken from the 
memory map. It includes the estimate for the root job. 

The second %SAB call shown in Figure A-9 reserves memory that is not 
actually in the system. This system has only 128K bytes of memory. Thus 
addresses 2000:0 to OFFFFrF are not used. Reserving these locations 
speeds the system initialization process. 



%SYSTEM MACRO CALL 

Figure A-10 shows the completed worksheet for the %SYSTEM call. You must 
place this call last in the configuration file. 
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EXAMPLE SYSTEM CONFIGURATION 



Macro c 

Number 

CONFIGU 


all: SYSTEM (system parameters) 




of calls required: exactly one 




RATION FILE NAME: CONFIG. A86 




FORMAT: 


suggested 






parameter type default 


value 


%SYSTEM 


(nucleus entry, base 


ICO 




rod size, word (0) 


20 




min trans size, word (64) 


64 




debugger, see note (A) 

1 
default e h provided, see note (N) 

2 
mode) word 


A 




D 




1 


NOTES: 






1. 


Valid entries for the debugger parameter include: 

A Debugger available 
N No Debugger available 




2 - 


Valid entries for the default e h provided parameter include: 




Y Yes 






D Debugger 






N No 




3. 


Types addr and base must be entered as hexadecimal 


numbers 




without the suffix H. Types word and byte default 


to 




decimal, but will accept all radix suffixes. 





Figure A-10. Completed %SYSTEM Macro Worksheet 
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EXAMPLE SYSTEM CONFIGURATION 

The parameters are described in the following: 

nucleus_entry This value is taken from the memory map. 

rod_size These values affect the system at run time. Use 

and the values listed in Figure A-10. 

min_t rans_si ze 

debugger The A indicates that the Debugger is available. 

default_e_h_provided The D indicates that the Debugger is used for 

the default exception handler. 

mode The 1 indicates that the Operating System 

transfers control to the exception handler (the 
Debugger) in the event of a programming error 
condition. 



CREATE THE ACTUAL CONFIGURATION FILE 

After you have filled out the macro worksheets, you can create the 
configuration file. To do this, create a file called CONFIG. A86 on your 
configuration diskette, and copy the information from the worksheets into 
it as well as an $INCLUDE statement for file CTABLE.MAC and an %END 
call. The statements in this file appear as follows: 

$INCLUDE (:F2: CTABLE.MAC) 
%SAB (0, 127A, U) 
%SAB (2000, FFFF, U) 

%JOB(0,1FFH,1FFH,OFFFH,OFFFFH,0,0:0,1,1,0,6B2:OOOD, 0,0:0, 512,0) 
%JOB(20,lFFH,0FFFFH,0FFFFH,0FFFFH,0,0:0,l,l,131,0E70:09O,0,llC5:0, 

0A04H,0) 
%SYSTEM (1C0, 20, 64, A, D, 1) 
%END 



GENERATE THE ROOT JOB 

You can now use the CROOT.CSD SUBMIT file to assemble the configuration 
file, link the root job, and locate the root job. Place the diskettes in 
the proper drives of your development system (system diskette in drive 
F0, coniguration diskette in drive Fl, Nucleus release diskette in drive 
F2, scratch and listing diskette in drive F3), and enter the following 
command: 

SUBMIT :F2:CR00T( CONFIG, date, 0E100H) 

Where date can be in any form, as long as it does not exceed nine 
characters. 



I 
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EXAMPLE SYSTEM CONFIGURATION 



This command assembles the configuration file, links it to the root job, 
and locates the root job at the correct address. LOC 86 places the 
located root job in file CONFIG on drive Fl. It also places the locate 
map for the root job in file CONFIG. MP2 on drive F3. You can use the 
locate map to determine the actual size of the root job. When you 
configure your ROM/ RAM system, you can update the memory map to reflect 
this value. 



LOAD THE SYSTEM 

At this point you can use either the ICE-86 in-circuit emulator or the 
iSBC 957A package to load the system into memory. When you do, load the 
following files, in order, from your configuration diskette: 

NUCLUS 
DEBUGR 
TBASIC 
CONFIG 
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APPENDIX B. BURNING THE NUCLEUS INTO 2732 PROM 



If you use the Universal PROM Mapper (UPM) version 3.0 to burn code into 
PROM, you cannot load the entire Nucleus with a single UPM READ command. 
In order to burn the Nucleus (and possibly some of your other programs), 
you must burn 16K byte pieces of the code into PROM. This appendix 
describes the procedures required to do this. It also lists the required 
hardware and software. Although this appendix refers specifically to the 
Nucleus, you can use the procedures described here to burn any large 
module into PROM. 



REQUIREMENTS 

In order to use the procedure outlined in this appendix, you must have 
the following hardware and software. 

• A linked Nucleus (NUCLUS.LNK) 

• LOC86 software 

• A UPP universal PROM Programmer with a 2732 personality module 

• 8 erased 2732A PROM modules 



With this hardware and software you can use the procedures in the 
following sections to place the Nucleus code into PROM. 



LOCATE THE NUCLEUS 

Use LOC86 to locate the Nucleus for a ROM/RAM configuration. Use a 
command similar to the following: 

L0C86 NUCLUS.LNK TO ROMNUC & 

ORDER (CLASSES (DATA, STACK, MEMORY)) & 

SEGSIZE (STACK (0)) & 

ADDRESSES (CLASSES (CODE (rom_address) , & 

(DATA (ram_address))) & 

MAP PRINT (map_file) & 
0BJECTC0NTR0LS ( NOLINES , NOCOMMENTS , 
NOPUBLICS , N0SYMB0LS ) 
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BURNING THE NUCLEUS INTO 2732 PROM 



Chapter 5 describes the parameters of this command in detail. However, 
for the discussion in this appendix, the important parameter is 
rom_address. This parameter specifies the address in ROM where the 
Nucleus will reside. 

Also examine the locate map to determine the exact size of the code 
class. You need this information to determine the number of pieces to 
burn. 



BURN THE CODE INTO PROM 

To burn the code into PROM, insert the 2732 personality module into the 
appropriate program socket (this appendix assumes socket 2). Then enter 
the commands shown in Figure B-l. These commands are structured so that 
you can place them in a SUBMIT file. The CNTL/E (control/E) characters 
in the figure return control to you so that you can insert a PROM into 
the UPP. After doing this, enter another CNTL/E to return control to the 
SUBMIT file. Make sure to place a new PROM into the UPP before each 
PROGRAM statement. 



UPM 

2732 

S0CKET=2 

READ OBJECT FILE :F2:R0MNUC FROM TO 3FFFH START 0E8000H 

STRIP LOW FROM TO 3FFFH INTO 4000H 

STRIP HI FROM TO 3FFFH INTO 6000H 

CNTL/E PROGRAM FROM 4000H TO 4FFFH START 

CNTL/E PROGRAM FROM 6000H TO 6FFFH START 

CNTL/E PROGRAM FROM 5000H TO 5FFFH START 

CNTL/E PROGRAM FROM 7000H TO 7FFFH START 

READ OBJECT FILE :F2:R0MNUC FROM TO 2AF9H START 0EC000H 

STRIP LOW FROM TO 2AF9H INTO 4000H 

STRIP HI FROM TO 2AF9H INTO 6000H 
CNTL/E PROGRAM FROM 4000H TO 4FFFH START 
CNTL/E PROGRAM FROM 6000H TO 6FFFH START 
CNTL/E PROGRAM FROM 5000H TO 557DH START 
CNTL/E PROGRAM FROM 7000H TO 757DH START 

EXIT 



Figure B-l. UPM SUBMIT File to Burn the Nucleus into PROM 
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BURNING THE NUCLEUS INTO 2732 PROM 



The commands in Figure B-l assume that the Nucleus code class ranges from 
OE8000H to 0EEAF.-9. You must modify the SUBMIT file to specify the 
correct addresses for your system. To give you a better understanding of 
how to do this, the individual UPM commands used to burn the first 
portion of the Nucleus are listed and discussed in detail. 



READ OBJECT FILE :F2:R0MNUC FROM TO 3FFFH START 0E8000H 

This command reads the first piece of the object file from disk into 
a 16K INTELLEC memory buffer. The logical addresses of the memory 
buffer are through 3FFFH. The absolute address of the module is 
specified as 0E8000H. 



STRIP LOW FROM TO 3FFFH INTO 4000H 

This command separates the even address (low order) bytes from the 
file and copies them into another memory buffer. 



STRIP HI FROM TO 3FFFH INTO 6000H 

This command separates the odd address (high order) bytes from the 
file and copies them into another memory buffer. 



CNTL/E PROGRAM FROM 4000H TO 4FFFH START 

This command burns the first half of the low order bytes into PROM. 
Make sure that you insert a 2732 PROM into the UPP before entering 
this command. Include the CNTL/E character only if you use a SUBMIT 
file. This character returns control to you so that you can insert 
the PROM. After you do, enter another CNTL/E and processing resumes. 



CNTL/E PROGRAM FROM 6000H TO 6FFFH START 

This command burns the first half of the high order bytes into PROM. 

CNTL/E PROGRAM FROM 5000H TO 5FFFH START 

This command burns the second half of the low order bytes into PROM. 
CNTL/E PROGRAM FROM 7000H TO 7FFFH START 

This command burns the second half of the high order bytes into PROM. 
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BURNING THE NUCLEUS INTO 2732 PROM 



The remainder of the commands in Figure B-l function similarly. For 
further information about UPM, refer to the UNIVERSAL PROM PROGRAMMER 
USER'S MANUAL. 

After you have burned all the PROMs, plug them into the memory board and 
test the system. 
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APPENDIX C. SYSTEM CALL USAGE 



This appendix lists the system calls used by fully-configured versions of 
the optional subsystems. This information is important when you decide 
which system calls to include in your final application system. Table 
C-l lists the system calls used by the Terminal Handler, Table C-2 lists 
those used by the Debugger, Table C-3 lists those used by the I/O System, 
Table C-4 lists those used by the Extended I/O System, Table C-5 lists 
those used by the Application Loader, and Table C-6 lists those used by 
the Human Interface. 



Table C-l. System Calls Used by the Terminal Handler 



NUCLEUS 


SYSTEM CALLS 


CATALOG$OBJECT 


GET$SIZE 


CREATE$MAILBOX 


GET$TASK$TOKENS 


CREATE$SEGMENT 


GET$TYPE 


CREATE$TASK 


RECEIVE$MESSAGE 


DELETE $SEGMENT 


SEND$MESSAGE 


DISABLE 


SET$ INTERRUPT 


ENABLE 


SIGNAL$ INTERRUPT 


END$INIT$TASK 


WAIT$ INTERRUPT 


EXIT$ INTERRUPT 
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SYSTEM CALL USAGE 



Table C-2. System Galls Used by the Debugger 



NUCLEUS 


SYSTEM CALLS 


CATALOG$OBJECT 


GET$SIZE 


CREATE$JOB 


GET$TASK$TOKENS 


CREATE $MAILBOX 


LOOKUP$OBJECT 


CREATE $ SEGMENT 


RECEIVE$MESSAGE 


CREATE$TASK 


RESUME$TASK 


DELETE$ SEGMENT 


SEND$MESSAGE 


DISABLE 


SET$ INTERRUPT 


DISABLE$DELETION 


SET$PRIORITY 


ENABLE 


SIGNAL$ INTERRUPT 


ENABLE$DELETION 


SLEEP 


END$INIT$TASK 


SUSPEND$TASK 


EXIT$ INTERRUPT 


WAIT$INTERRUPT 


GET$PRIORITY 





Table C-3. System Calls Used by the I/O System 



NUCLEUS SYSTEM CALLS 


CATALOG$OBJECT 


DI SABLE $DELET ION 


SEND$ CONTROL 


CREATE$COMPOSITE 


ENABLE $DELETION 


SEND$MESSAGE 


CREATE$EXTENSION 


END$INIT$TASK 


SET$ INTERRUPT 


CREATE$MAILBOX 


FORCE$DELETE 


SET$OS$EXTENSION 


CREATE$REGION 


GET$LEVEL 


SIGNAL$EXCEPTION 


CREATE$SEGMENT 


GET$TASK$TOKENS 


SIGNAL$ INTERRUPT 


CREATE$TASK 


GET$TYPE 


SLEEP 


DELETE$COMPOSITE 


LOOKUP$OBJECT 


UNCATALOG$OBJECT 


DELETE$MAILBOX 


RECEIVE$CONTROL 


WAIT$ INTERRUPT 


DELETE $REG ION 


RECEIVE$MESSAGE 




DELETE$ SEGMENT 


RESET$ INTERRUPT 




DELETE $TASK 


RESUME$TASK 
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Table C-4. System Calls Used By the Extended I/O System 



NUCLEUS SYSTEM CALLS 


BASIC I/O SYSTEM CALLS 


CATALOG$OBJECT 


DELETE$MAILBOX 


A$ATTACH$FILE 


CREATE$COMPOSITE 


DELETE$ SEGMENT 


A$CHANGE$ACCESS 


CRETE $EXTENSION 


GET$TASK$TOKENS 


A$CLOSE 


CREATE$JOB 


GET$TYPE 


A$CREATE$DIRECTORY 


CREATE$MAILBOX 


LOOKUP $OBJECT 


A$CREATE$FILE 


CREATE $REGION 


RECEIVE$CONTROL 


A$DELETE$CONNECTION 


CREATE$ SEGMENT 


RECEIVE$MESSAGE 


A$DELETE$FILE 


CREATE$TASK 


SEND$ CONTROL 


A$GET$CONNECTION$ STATUS 


DELETE$COMPOSITE 


SEND$MESSAGE 


A$GET$FILE$ STATUS 


DELETE $ JOB 


SET$OS$EXTENSION 


A$OPEN 




UNCATALOG$OBJECT 


A$PHYSICAL$ATTACH$DEVICE 

A$PHYSICAL$DETACH$DEVICE 

A$READ 

A$RENAME$FILE 

A$SEEK 

A$ SPECIAL 

A$TRUNCATE 

A$WRITE 






CREATE$USER 





Table C-5. System Calls Used by the Application Loader 



NUCLEUS SYSTEM CALLS 


I/O SYSTEM SYSTEM CALLS 


EXTENDED I/O SYSTEM CALLS 
(if load job features 
are included) 


CATALOG$OBJECT 


A$ATTACH$FILE 


CREATE$IO$JOB 


CREATE$MAILBOX 


A$ DELETE $CONNECTION 


S$ATTACH$FILE 


CREATE$SEGMENT 


A$ CLOSE 


S$DELETE$CONNECTION 


CREATE$TASK 


A$OPEN 




DELETE$JOB 


A$READ 




DELETE$MAILBOX 


A$SEEK 




DELETE$SEGMENT 






DELETE$TASK 






END$INIT$TASK 






GET$POOL$ATTRIB 






LOOKUP $OBJECT 






RECEIVE$MESSAGE 






SEND$MESSAGE 






SET$EXCEPTION$HANDLER 






SET$OS$EXTENSION 
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Table C-6. System Calls Used by the Human Interface 



NUCLEUS SYSTEM CALLS 


CATALOG$OBJECT 


GET$TYPE 


CREATE$MAILBOX 


LOOKUP$OBJECT 


CREATE$REGION 


RECEIVE$CONTROL 


CREATE$SEGMENT 


RECEIVE$MESSAGE 


CREATE$SEMAPHORE 


RECEIVE $UNITS 


CREATE $TASK 


SEND$ CONTROL 


DELETE$JOB 


SEND$MESSAGE 


DELETE $MAILBOX 


SEND$UNITS 


DELETE$ SEGMENT 


SET$EXCEPTION$HANDLER 


END$INIT$TASK 


SET$OS$EXTENSION 


GET$SIZE 




GET$TASK$TOKENS 




BASIC I/O SYSTEM CALLS 


A$ATTACH$FILE 


A$WRITE 


A$DELETE$CONNECTION 


GET$TIME 


A$GET$CONNECTION$STATUS SET$TIME 


A$OPEN 




A$PHYSICAL$ATTACH$DEVICE 


A$READ 




EXTENDED I/O i 


SYSTEM CALLS 


EXIT$IO$JOB 


S$GET$FILE$STATUS 


S$ATTACH$FILE 


S$OPEN 


S$CHANGE$ACCESS 


S$READ$MOVE 


S$CREATE$FILE 


S$RENAME$FILE 


S$DELETE$CONNECTION 


S$SEEK 


S$DELETE$FILE 


S$ SPECIAL 


S$GET$CONNECTION$STATUS S$TRUNCATE 


S$GET$EXTENSION$DATA 


S$WRITE$MOVE 


APPLICATION LOADER 


SYSTEM CALLS 


A$LOAD 




A$LOAD$IO$JOB 


_. -. ..-,. - 
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